| Header file: | form.h |
| Object name: | fFORM |
| Object index: | 1 of 1 Object |
This object would be more aptly named fWINDOW, but already that would break enough code to make it a hassel. This class simply makes a window and deals with it - a plain, ordinary window that you can do things with. Nice and simple... and this class handles some of the things that are nice to do with a window as well. And of course, events for the window are handled too... which is handy.
| Name | Description | Value |
| fsUsual | This would be the usual style that you would apply for the primary style of a window. If you are mixing other primary styles, you might like to mix this one too to make sure that the window works correctly. | WS_EX_CONTROLPARENT | WS_EX_APPWINDOW |
| fsStayOnTop | This style makes the window stay on top of all other windows. You can set this dynamically through methods documented in the methods table which might be more useful. | WS_EX_TOPMOST |
| fsDragAndDrop | This style allows the window to have files dragged over it, and registers the window as a window capable of handling these drops. Generally you may not need this style, as the fDRAGANDDROP object registers the window for you when you use it, but this may still be handy. | WS_EX_ACCEPTFILES |
| fsSunkenEdge | This style gives the window a sunken edge... for something a little different. | WS_EX_CLIENTEDGE |
| fsHelpButton | This style adds a help button to the other buttons at the top right hand corner of your window. I think that if you do this, you'll have to handle some extra messages in the message queue, none of which I know about. | WS_EX_CONTEXTMENU |
| fsDoubleBorder | This style gives you window a double border... or in other words, a thicker border. | WS_EX_DLGMODALFRAME |
| fsToolWindow | This style makes the window into a tool window. A tool window will automatically stay on top, have only a close button, and will not show up on the taskbar. Handy for a toolbar. | WS_EX_TOOLWINDOW |
| fsTransparent | This style is a funny one... it seems that it makes a transparent window in the sense that a window with this style is only painted after all the sibling windows have been painted. | WS_EX_TRANSPARENT |
| fsPaletteWindow | This style makes the window the same as if it was a toolwindow, with a single border. | WS_EX_PALETTEWINDOW |
| fsMDIClient | This style makes this window a child of another window - just like a window in a MDI - Multiple Document Interface. The F3C has no support for MDI windows, so you'll have to figure this one out yourself. | WS_EX_MDICHILD |
| Name | Description | Value |
| fsNoBorder | This style creates a window with no border or title bar. | WS_POPUP | WS_CLIPCHILDREN | WS_CLIPSIBLINGS |
| fsThinBorder | This style makes the window have a thin, unsizable border. The user will be unable to resize one of these windows. | WS_POPUPWINDOWS | WS_CLIPCHILDREN | WS_CLIPSIBLINGS |
| fsNoSysMenu | This style creates a window that has a title bar but does not have the buttons that are usually at the right hand side of the window. | WS_DLGFRAME | WS_CLIPCHILDREN | WS_CLIPSIBLINGS |
| fsNormal | This style creates a normal window that you usually see all over the place. It can be resized by the user, it has a border, and it has a title bar with the usual 3 buttons. | WS_OVERLAPPEDWINDOW | WS_CLIPCHILDREN | WS_CLIPSIBLINGS | WS_GROUP |
| The following options are a little different. Whereas the above options are a mixture of styles to create one type of object, the following styles are by themselves. You can mix them up to make more customised objects. You mix the styles with the OR (|) operator. You can even mix them with the above styles to enhance them further. Mix and match away! | ||
| stMaximizeButton | This option makes the window show the maximize button. | WS_SYSMENU | WS_MAXIMIZEBOX |
| stMinimizeButton | This style makes the window have a minimize button. | WS_SYSMENU | WS_MINIMIZEBOX |
| stTitleBar | This style makes the window have a title bar. | WS_CAPTION |
| stThinBorder | This style makes the window have a thin border that can not be resized by the user. | WS_BORDER |
| stSizeableBorder | This style makes a window that has a border which can be resized by the user. | WS_SIZEBOX |
| stUsual | This style should be included with any mix-and-match window styles to make it accept controls and draw them properly. Otherwise you will find that the controls do not appear correctly, and do not redraw properly. | WS_CLIPCHILDREN | WS_CLIPSIBLINGS |
| Name | Description |
| HWND Handle; | This is the windows handle, as given by windows when the window was created. You can write to this if you want to, but unless you're fairly sure of what you are doing, just read the handle from it. |
| HWND Parent; | This is the parent window, as specified when you created the window. If you did not specify a parent window when you created the window, then this variable will be empty, and changing it will have no effect at all unless you recreate the window. |
| bool SubClass; | This variable, when set to TRUE, will enable the windows message queue to be subclassed for the GUI controller. It is by default TRUE, and only relevant if you have a GUI controller. By setting this to FALSE, the GUI controller will not subclass this window, and thus all messages sent to this window will be sent to the usual application message queue. All the events listed in the events table will not work if you do not subclass the window. |
| bool RepaintOnResize; | This variable sets whether or not to repaint the window when you tell it to resize itself. Failing to repaint when moving the window or making the window bigger will make things look a little funny, but there may be some occasions when you do not want to repaint it. This is TRUE by default. |
| bool DontDestroy; | When the class is destroyed, the deconstructor will destroy the window along with it - but that can be a problem sometimes (it was for me!). By default, this is FALSE, allowing the deconstructor to destroy the window. Setting this to true will prevent the deconstructor from destroying the window. Simple! |
| bool QuitOnFormClose; | With the GUI controller, the event OnClose becomes available. If you should wish to have this OnClose handler quit your application, then you can set this to true. After that, you can set your OnClose handler to a function. Make this function return TRUE, and the window will not only be allowed to close, but the application will terminate too. Return FALSE, and nothing will happen at all. If this is FALSE (as is the default) the application will NOT quit when this window is destroyed. |
| HMENU Menu; | Through this member you can set the menu that will be the main menu at the top of the window. You will need to set this member before you create the window, or otherwise it will have no effect. You might like to set the menu through the fMAINMENU controller instead, which allows you to build menus dynamically and apply menus dynamically. |
| LRESULT RetVal; | This is the number to return to the message queue that this windows message queue was called from, if relevant. What does this mean? Not a thing if you don't use a GUI controller, but if you do... it's too hard to explain here. It will be explained in the events section - look for the WindProc event. |
| Prototype | Description |
|
void CreateForm(char* Title, int PrimaryStyle, int SecondaryStyle); void CreateForm(char* Title, int PrimaryStyle, int SecondaryStyle, HWND Parent); void CreateForm(char* ClassName, char* Title, int PrimaryStyle, int SecondaryStyle); void CreateForm(char* ClassName, char* Title, int PrimaryStyle, int SecondaryStyle, HWND Parent); | All of these functions actually create the window, but all slightly differently. Each passed variable has a different effect, and there are several combinations of variables. Title is the title of the window, shown in the titlebar at the top of the window (if applicable). The Primary Style is one or more of the styles listed in the primary options table at the top of this document. The Secondary Style is one or more of the styles listed in the secondary options table near the top of this document. Parent is the parent window, if that is applicable (as it may be in the case of a MDI window). ClassName is the name of the window class that your application uses (that you registered at the start of the program via the APPLICATION interface). You do not need to specify ClassName if you do not want to, as the window can automatically find out the class name from the global APPLICATION object. This function returns TRUE if the window was created without any problems. |
| void Destroy(void); | This function destroys the window. |
| void ShowForm(int Method); |
This function shows the window in the specified way. Normally you would pass the value that you got from WinMain to show the window the first time during your programs execution, but after that, you can use one of the following numbers to show the window differently: (taken from the Win32 SDK Reference manual)
|
| bool IsVisible(void); | This function returns TRUE if the window is visible. |
| void UpdateForm(void); | This function updates the window. |
| HWND GetHandle(void); |
This function returns the handle of the window. You should use this function instead of the Handle member to retrieve the handle.
|
|
void Left(int Left); int Left(void); | These functions set or get the left position of the window. |
|
void Top(int Top); int Top(void); | These functions set or get the top position of the window. |
|
int Right(void); int Bottom(void); | These functions return the position of the right and bottom edges of the window in relation to the desktop. You can only retrieve these values, not set them. |
|
void Width(int Width); int Width(void); | These functions set or get the width of the window. |
|
void Height(int Height); int Height(void); | These functions set or get the height of the window. |
|
void CWidth(void); void CHeight(void); | These functions return the width and height of the client area of the window, respectively. The client area of a window is the area that is available for use - ie. that area that is not consumed by the title bar and borders. You can use this when deciding the size and position of controls on the window. |
| void SetPos(int X, int Y); | This function sets the position of the window. |
| void SetSize(int Width, int Height); | This function sets the width and the height of the window together. |
| void SetAll(int X, int Y, int Width, int Height); | This function sets the position, width and height all together. |
| void Center(void); | This function centers the window on the screen. |
| void SetCaption(char* Caption); | This function sets the caption (or title) of the window. |
| char* GetCaption(void); | This function returns the caption of the window. |
| void Morph(int PrimaryOptions, int SecondaryOptions); | This function changes the Primary and Secondary options for the window after it has been created. Please note that the window may need to be updated afterwards, and some of the changes that you have made may not occur. |
| void SetStayOnTopStatus(bool Set); | This function sets whether or not the window stays on top of other windows. Pass TRUE to make the window stay on top, or FALSE to unset this style. |
| void SetWindowProceedure(WNDPROC WindProc); |
This function subclasses the window so that all messages sent to it go to the specified Window Proceedure. The old window proceedure is saved to the member OlderWndProc. When you are finished in you subclassed message queue, be sure to call CallWindowProc(Window->OlderWndProc, hwnd, Message, wParam, lParam);
|
Please see the chapter on event handling for information on how to use these correctly.
| Prototype | Description | Sent under |
| bool (*OnClose)(fFORM* Sender); |
This event occurs when the user clicks the close button in the top right hand corner or the window. You can return TRUE from this function to allow the close to continue, or FALSE to make the window stay. If you set the member QuitOnFormClose to TRUE, the application will terminate when you close the window.
| WM_CLOSE |
| void (*OnShow)(fFORM* Sender, bool Show, int Other); |
This event occurs when the window is shown. Show will be TRUE if the window is being shown, or FALSE if it is being hidden. Other can be one of the following values, to specify what happened to the window: (taken from the Win32 SDK Reference manual)
| WM_SHOWWINDOW |
| void (*OnResize)(fFORM* Sender, int Type, int Width, int Height); |
This event occurs when the user has resized the window, and what those dimenstions are, and also how it occured. Width and Height are the new width and height, whilst type is one of the following values: (taken from the Win32 SDK Reference Manual)
| WM_SIZE |
| void (*OnSizing)(fFORM* Sender, int Edge, RECT* Size); |
This event occurs when the form is being resized by the user. This event occurs repeatedly whilst the user changes the size. The Size parameter is a RECT structure which specifies where the drag rectangle is currently. You may change members of this to change where the window is currently. The other parameter specifies what edge is being resized, and is one of the following values: (taken from the Win32 SDK Reference Manual)
| WM_SIZING |
| void (*OnMove)(fFORM* Sender, int X, int Y); | This event occurs when the window has been moved. The two parameters are the new location of the window. | WM_MOVE |
| void (*OnMoving)(fFORM* Sender, int Side, RECT* Rect); |
This event occurs when the user is moving the window. This message is sent repeatedly as the user drags the window. The Rect parameter is a pointer to a RECT structure, which you can change to change where the window is. Side is one of the following values: (taken from the Win32 SDK Reference Manual)
| WM_MOVING |
| void (*OnCreate)(fFORM* Sender); | This event occurs when the window is created. Please note that due to restrictions on how the classes work, this is called manually from the Internal_CreateWindow() function. | WM_CREATE? |
| void (*OnDestroy)(fFORM* Sender); | This event occurs when the window is destroyed by either closing the button or something that you have done with the class. | WM_DESTROY |
|
void (*OnLMouseDown)(fFORM* Sender, int Keys, int X, int Y); void (*OnLMouseUp)(fFORM* Sender, int Keys, int X, int Y); void (*OnLDBLClick)(fFORM* Sender, int Keys, int X, int Y); void (*OnRMouseDown)(fFORM* Sender, int Keys, int X, int Y); void (*OnRMouseUp)(fFORM* Sender, int Keys, int X, int Y); void (*OnRDBLClick)(fFORM* Sender, int Keys, int X, int Y); void (*OnMMouseDown)(fFORM* Sender, int Keys, int X, int Y); void (*OnMMouseUp)(fFORM* Sender, int Keys, int X, int Y); void (*OnMDBLClick)(fFORM* Sender, int Keys, int X, int Y); |
All of these events occur when the user does something with the mouse inside the windows client area. All the functions with L relate to the left button, R to the right button, and M to the middle button. X and Y are the location at which these events occured. Keys can be one of the following values: (taken from the Win32 SDK Reference Manual)
| WM_LBUTTONDOWN, WM_LBUTTONUP, WM_LBUTTONDBLCLK, WM_RBUTTONDOWN, WM_RBUTTONUP, WM_RLBUTTONDBLCLK, WM_MBUTTONDOWN, WM_MBUTTONUP, WM_MBUTTONDBLCLK, |
| void (*OnMouseMove)(fFORM* Sender, int Keys, int X, int Y); |
This event occurs when the user moves the mouse over the client area of the window. X and Y specify where the mouse ended up. Keys can be one of the following values: (taken from the Win32 SDK Reference Manual)
| WM_MOUSEMOVE |
|
void (*OnKeyPress)(fFORM* Sender, int Key, LPARAM lParam); void (*OnKeyDown)(fFORM* Sender, int Key, LPARAM lParam); void (*OnKeyUp)(fFORM* Sender, int Key, LPARAM lParam); |
These events are sent when something happens on the keyboard relevant to the window in question. Key is a virtual key code, or the ASCII equivilent of the key if it was a letter key. For example, you'd check this against things like VK_ESCAPE, VK_CTRL, and so forth. Here is a list of virtual key codes. lParam is extra information which you may not need, but here is what the Win32 SDK Reference Manual says about it: "Value of lParam. Specifies the repeat count, scan code, extended-key flag, context code, previous key-state flag, and transition-state flag, as shown in the following table: Value - Description 0-15 - Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key. 16-23 - Specifies the scan code. The value depends on the original equipment manufacturer (OEM). 24 - Specifies whether the key is an extended key, such as the right-hand ALT and CTRL keys that appear on an enhanced 101- or 102-key keyboard. The value is 1 if it is an extended key; otherwise, it is 0. 25-28 - Reserved; do not use. 29 - Specifies the context code. The value is always 0 for a WM_KEYDOWN message. 30 - Specifies the previous key state. The value is 1 if the key is down before the message is sent, or it is 0 if the key is up. 31 - Specifies the transition state. The value is always 0 for a WM_KEYDOWN message." I would assume that the numbers are the numbers of bits inside the lParam number (ie. 0-15 would mean the first 16 bits of the number). | WM_CHAR, WM_KEYDOWN, WM_KEYUP |
| void (*OnPaint)(fFORM* Sender); | This event occurs when the window needs to be repainted. | WM_PAINT |
| void (*OnGainFocus)(fFORM* Sender); | This event occurs when the window gains focus. | WM_SETFOCUS |
| void (*OnLoseFocus)(fFORM* Sender); | This event occus when the window loses focus. | WM_KILLFOCUS |
| bool (*WindProc)(fFORM* Sender, UINT Message, WPARAM wParam, LPARAM lParam); | When the GUI controller looks for events, it can pass along that message queue to another one that you specify if you want. Here you specify that message queue. When running this message queue, you need to do a few special things. Ordinarily the GUI controller will return the default action, but if it allows this message queue to gain control, it will be unable to do so. So if you want to return a value from this message queue back to windows, return TRUE in this function, and put the value that you want returned in the RetVal member of the Sender window. This value will be returned instead of the default action. Please see the example code for how to use this. | WM_Anything |
| void (*OnDropFiles)(fFORM* Sender, HDROP Drop); | This event occurs if your window is registered to handle dragged and dropped files, and the user did drag and drop files onto this window. You can then handle the dropped files, or use the fDRAGANDDROP object to gather the files for you. | WM_DROPFILES |
The following snippet gives a basic idea of how to use this component.
//First we create the window....
fFORM Window;
Window.CreateForm("Hello there!", fsUsual, fsNormal);
Window.Center();
//Now some events stuff.
bool CheckClose(fFORM* Sender)
{
//This will be called when we want to close
//the window.
//Ask if we want to close the window...
if (MessageBox(Sender->GetHandle(), "Are you sure you want
to close this window?", Sender->GetCaption(),
MB_ICONWARNING | MB_YESNO) == IDYES)
{
//Ok, so you do want to close the window.
return TRUE;
} else {
//I see you don't want to close the window...
return FALSE;
}
};
Window.OnClose = &CheckClose;
//Now, how do we use this WndProc thingy for the Window?
//Like so...
Window.WindProc = &FormWindowProc;
bool FormWindowProc(fFORM* Sender, UINT Message, WPARAM wParam, LPARAM lParam)
{
... Handle your messages like usual ...
//Say we want to return a value for the WM_THINGY message.
case WM_THINGY:
//Do some stuff...
//Then prepare the return value...
Sender->RetVal = ReturnValue;
return TRUE;
break;
... Rest of message handling ...
//Must return FALSE!!
//If you are not returning anything else.
return FALSE;
};
| Back to index | The FreeFoote Foundation Classes Documentation |