fSCREEN

Quick Data

Header file:screen.h
Object name:fSCREEN
Object index:1 of 1 Object

General Description

The fSCREEN class is a class designed to allow you to have access to some fairly standard but incredibly useful functions dealing with the physical screen with which you are displaying things on. You can change screen modes, enumerate possible screen modes, or just get information.

As there should not be a need for anymore than one instance of this class, a global object is already created for you when you include this file. That object is called Screen. If you really don't want this global object, then just #define F_SCREEN_NO_GLOBAL before you include the file.

Methods

Prototype Description
int GetScreenHeight(void); This function returns the number of pixels high that the current screen's display is.
int GetScreenWidth(void); This function returns the number of pixels wide that the current screen's display is.
int GetBorderWidth(void);
int GetBorderHeight(void);
int Get3DBorderWidth(void);
int Get3DBorderHeight(void);
int GetCursorHeight(void);
int GetCursorWidth(void);
int GetIconWidth(void);
int GetIconHeight(void);
int GetSmallIconWidth(void);
int GetSmallIconHeight(void);
int GetMenuButtonWidth(void);
int GetMenuButtonHeight(void);
 All of these functions retrieve values corresponding to the sizes of various things on the system. These values can change, as set by the user - so if you need to deal with these things, find them out first with these functions. Now I shall describe these functions, starting with the top group.
'Border' refers to the outside border of a window. You can specify a window to just have a border, which would be a 1-pixel thick (generally) black line around the edge of a window. On Windows 95 or later, you could have 3D borders. These functions retrieve the width and height of these borders.
The cursor height and width refers to the height and width of the mouse cursor - or the size of a bounding box around the mouse cursor.
Icon sizes - the user can, if they decide, enlarge the icons used by the system. Many people complain that when their monitor is at a high resolution the icons are too small. So you can change them. The default size is 32x32. If you are dealing with icons, you may like to check. Similarly, there are small icons, which are smaller versions of the normal icons. Generally these are half the size of the normal icons - but again, if you need to, check.
The last two functions return the size of the buttons on the titlebar - you know, the 'X' and '_' buttons. Height specifies the height of them, and Width specifies the width of them.
int ChangeDisplayNow(int Width, int Height, int Bits); This function forces Windows to change the displays screen mode right now to the settings that you specify, if it can. Width and Height specify the resolution - so pick one that does exist. Bits specifies the bit-depth to change to - and this can be 2, 4, 8, 16, 24, or 32. Please note that some devices support either 24 or 32, but not both (like my GeForce2 MX, which only supports 4, 8, 16, and 32). This function returns one of the following values (taken from the Win32 SDK Reference Manual):
  • DISP_CHANGE_SUCCESSFUL - The settings change was successful.
  • DISP_CHANGE_RESTART - The computer must be restarted in order for the graphics mode to work.
  • DISP_CHANGE_BADFLAGS - An invalid set of flags was passed in.
  • DISP_CHANGE_FAILED - The display driver failed the specified graphics mode.
  • DISP_CHANGE_BADMODE - The graphics mode is not supported.
  • DISP_CHANGE_NOTUPDATED - Windows NT only: Unable to write settings to the registry.
When you are done, you can reset the normal screen mode by calling the ScreenReset() function. The screen mode that you apply here does not apply permanently.
int ChangeDisplayPermanent(int Width, int Height, int Bits); This function does exactly the same thing as the ChangeDisplayNow() function, but it saves the changes for later - ie. Windows will always use this mode after you call this function. Everything else related to this function is exactly like it is for the ChangeDisplayNow() function.
int ChangeDisplayTest(int Width, int Height, int Bits); This function is almost exactly like the ChangeDisplayNow() function, except that it doesn't actually change the mode. Instead, it tests the mode, to see whether or not that mode is possible under the current hardware. If it is, it will return DISP_CHANGE_SUCCESSFUL. Otherwise it will return something else. For all of the other possible return values, please see the documentation for the ChangeDisplayNow() function above.
void ScreenReset(void); This function makes Windows reset whatever current screen mode is applied back to whatever is stored in the registry as the current screen settings. You should call this whenever your application quits if you have dynamically changed the screen mode, but not saved the mode. Otherwise the screen will stay at whatever resolution you set it to, which can be rather annoying...
void StartModeEnumerate(void); This function prepares Windows to begin enumerating the screen modes available on the current monitor. You can use the following functions to determine what those screen modes are. You must call this function first, or otherwise your enumeration will not work.
bool EnumerateMode(int Index); This function enumerates the specfied mode. You just need to start counting from 0 (Zero), and pass that number to this function, and then retrieve the information that you want. When this function returns FALSE, you will know that there are no more modes to enumerate, and you can stop counting.
int GetEScreenHeight(void);
int GetEScreenWidth(void);
int GetEBitDepth(void);
int GetEDisplayFreq(void); 		These functions return information about the screen mode that you just enumerated. After enumerating the mode, you can read these to determine what that mode is. If you are still confused about this, then please look at the example code to see how to use this.

Sample Code

The following snippet gives a basic idea of how to use this component.


//Just change the mode, now. To 640x480x24bpp.
if (Screen.ChangeDisplayNow(640, 480, 24) == DISP_CHANGE_SUCCESSFUL)
   {
   //All was ok! Mode changed!
   } else {
   //Not ok. Mode not changed.
   }

//When you are done, reset.
Screen.ScreenReset();

//Now list all the resolutions supported.
Screen.StartModeEnumerate(void);
for (int Temp = 0; ; Temp++)
    {
    if (!Screen.EnumerateMode(Temp)) break; //Stop if FALSE.
    ... = Screen.GetEScreenHeight();   //Get Height
    ... = Screen.GetEScreenWidth();    //Get Width
    ... = Screen.GetEScreenBitDepth(); //Get Bitdepth
    ... = Screen.GetEDisplayFreq();    //Get Frequency
    }
//No cleanup required!
Back to indexThe FreeFoote Foundation Classes Documentation