@database foxgui.guide @author "Simon Fox" @(c) "Copyright © 1991-7 Foxysoft" @$VER: FoxGui 4.1 Documentation @node Main "FoxGui Documentation" @{b}FoxGui - The Amiga Graphical User Interface Tools@{ub} Version 4.1 Copyright © 1991-7 FoxySoft @{" Introduction " Link Introduction} @{" System requirements " Link SystemRequirements} @{" Compatibility " Link Compatibility} @{" Format of a FoxGui program " Link Format} @{" Functions " Link Functions} @{" Multi-threading " Link MultiThreading} @{" Drag/Drop functionality " Link DragDropFunc} @{" Suggestions " Link Suggestions} @{" Bugs (what bugs?) " Link Bugs} @{" Wish list " Link WishList} @{" Adding your own gadgets to FoxGui " Link AddGadget} @{" What's new in release 4.2? " Link WhatsNew42} @{" What was new in release 4.1? " Link WhatsNew41} @{" What was new in release 4.0? " Link WhatsNew4} @{" What was new in release 3.0? " Link WhatsNew3} @{" What was new in release 2.0? " Link WhatsNew2} @{" Important notice. " Link Notice} @endnode @node DragDropFunc "Drag/Drop support in FoxGui applications" @{b}What is drag/drop?@{ub} Drag/drop is a way of allowing a user to move data around the user interface in a very visual manner. It's achieved by pointing the mouse at the control/data/image that you want to drag, pressing down and holding down the left mouse button, moving the mouse (with the button still held down) to the point at which you wish to drop the control/data/image and then letting go of the mouse button. Of course, a user shouldn't really expect to be able to pick up any object on the screen and drag it to just anywhere they like and drag/drop isn't always the most appropriate way of achieving things but it's an increasingly popular option. Here's an example of a situation in which drag/drop might be suitable. An application was been written to allow customers to order components from a manufacturer. Having reached the screen showing details of the components available (in a list-box for example), the user now has to select which items she wants to order. One way to do this is to have another list-box on the screen showing a list of components ordered. To order a component, the user could drag an item from the available components list-box into the components ordered list-box. If the application is well written it should have alternative ways of doing the same thing, for example double-clicking on an item in the available components list might copy that item into the items ordered list. There might also be an "order component" button on the screen which, when clicked on copies the currently hilighted component in the available components list into the ordered components list. Not all FoxGui controls are drag/drop aware. The chart below shows which controls have drag-drop functionality: Control Functions supported ------- ------------------- List Boxes DRAG and DROP Frames DRAG and DROP Windows DROP only. @{b}How do I use it?@{ub} When you create a FoxGui control you usually pass a "flags" parameter which allows various options to be specified. List boxes, frames and windows have drag/drop flags available which specify whether or not data can be dragged out of or dropped into the control. The flags are summarised below. Control Drag flag Drop flag ------- --------- --------- List Box LB_DRAG LB_DROP Frame FM_DRAG FM_DROP Window - GW_DROP Although the example application described above allows data to be dragged from one list box into another it is important to realise that data dragged from any control can be dropped into any other drag/drop aware control which was created with the relevant flags set. The originating and receiving controls need not be of the same type. If a control (a list box for example) is created with the LB_DRAG and LB_DROP flags specified then data can be: * Dragged from that list box to another drag/drop control. * Dragged from other drag/drop controls into that list box. * Dragged from that list box into itself! When you specify drag or drop flags for a control you will also have to create a function which will handle the drag and drop (and possibly other) events. More details about these functions are described in the @{" MakeListBox " Link MakeListBox}, @{" MakeFrame " Link MakeFrame} and @{" OpenGuiWindow " Link OpenGuiWindow} function descriptions elsewhere in this documentation but some general principles are described below. Code which is called when a drag begins is typically used to set a pointer to the data being dragged. That pointer will be stored in memory associated with the object that the data is dragged from and can point to absolutely anything you want it to (a struct, an array of items, a FoxGui control, ... anything). Your drag event should really do nothing other than set that pointer but it can do other things as long as they are FAST! The drag event occurs just as the user starts to drag the data so if the function takes too long it will hold up the drop function when the user drops the data. Code which is called when a drop event occurs will typically do something with the data dropped into the control. The drop event function will be passed a pointer which was initialised by the drag event function containing information about what has been dragged. When writing a function to handle a drop event it's worth considering what to do if the data dropped onto the control was dragged from the same control (of course this needn't be considered if the control wasn't created with the relevant flag specified to allow data to be dragged from it). It's worth also considering that if the control also responds to left mouse button clicks then a slight movement of the mouse between pressing and releasing the button will cause up to three events to occur - the left click event, the drag event and the drop event (assuming that all three are enabled for that control). Often, data dragged from the same control should just be ignored but you will need to put code in your drop event to filter out such data. Drag and drop event functions should either return @{" GUI_END " Link GuiContinueEnd} or @{" GUI_CONTINUE " Link GuiContinueEnd} but it should be remembered that in the case of the DRAG event, the return value will be ignored. This makes it impossible to trigger the end of a FoxGui program at the point a user starts to drag data. Personally I think that would be very bad practise anyway and I can't see why you would want to do it. There are, however, other limitations on what you should do in a drag event. @{b}Drag event limitations@{ub} You should not create or destroy FoxGui controls from within a drag event function (this includes opening and closing windows). There are no such limitations for the DROP event. @endnode @node MultiThreading "Multi-threading in FoxGui applications" @{b}How to Multi-thread@{ub} From release 4.1 onwards, FoxGui has limited support for multi-threading. What this means is that while your program is performing a lengthy task the user is still free to use other controls in your application and have them respond in the normal way. This is very simple to arrange. Here's an example. Let's suppose that when the user clicks a certain button in your application, a list of files that the user has selected will be copied from one disk to another. The user may have selected many files and this might take some time. Other buttons in your application might show the contents of a disk or delete a file for example. There's no reason why the user shouldn't be able to do either of these things while the program is copying the original set of files that the user selected. Here's the function that copies the files: int CopyButtFn(PushButton *copy) { int NumFiles = GetNumFilesToCopy(); char *Filename = GetFirstFileName(); while (Filename != NULL) { CopyFile(Filename); Filename = GetNextFileName(); } return GUI_CONTINUE; } Normally when this function runs, nothing else can happen in your application until this function returns. Any other buttons you click on won't respond until the function has finished. FoxGui now has a new function @{" CheckMessages " Link CheckMessages}. When you call CheckMessages() FoxGui will immediately check whether there are any outstanding messages that it should respond to. These could be button clicks, scroll-bar drags, timer events, key presses - anything a user can do that your program should respond to. FoxGui will process any outstanding events it finds and then the CheckMessages function will return. We can make use of this to allow multi-threading by changing our example above as follows: int CopyButtFn(PushButton *copy) { int NumFiles = GetNumFilesToCopy(); char *Filename = GetFirstFileName(); while (Filename != NULL) { CopyFile(Filename); Filename = GetNextFileName(); CheckMessages(); } return GUI_CONTINUE; } Now after each file is copied the program will catch up with any other tasks it has been asked to perform before copying the next file. @{b}The pitfalls@{ub} Can multi-threading really be that simple? Well, almost. There are one or two pitfalls that are fairly easily avoided but may not be instantly obvious. There are probably more that should be listed here that I haven't thought of yet so I'm sure that over time this list will get longer. @{b}Close Window functions@{ub} It may be that your main task (in the example above this would be the CopyButtFn function) opens a window (you might want to have a progress bar in the window which displays the percentage of the task that has completed). In this case the while loop in the example above would also contain calls to the SetProgress function. If the window has a close button then it would be possible for the user to click the close button before the task was complete. The regular calls to CheckMessages() would ensure that in this case the window will get closed before the task has finished. Closing the window will obviously mean destroying the progress bar so after each subsequent file is copied, the SetProgress function will be passed a pointer to a progress bar which has already been destroyed. This is likely to cause severe problems - probably resulting in the computer crashing. Obviously this problem could be solved by not having a progress bar in the window. Without the progress bar, you may not even need the task to open a window (as in the example above). This is not a very good solution. It's good practice to have some sort of indication of progress when a lengthy task starts otherwise how will the user know that anything's happening? There are many better solutions to this problem: * Don't have a close button on the window. The program could automatically close the window once the task is complete. If the user doesn't want the window in the way they can always send it behind other windows. * Have a close function for the window which checks whether the process is complete and doesn't allow the user to close the window until it is. The process could set a flag at the start and reset it at the end so that the close function could determine whether the process is still running and prevent you from closing the window if it is. * Have the window's close function set a flag to say that the window has been closed. Modify the main function so that it doesn't call functions (such as SetProgress) which affect controls in the window if the window has already closed. If the process relies on the window being open for reasons other than displaying the progress then this may not be an option. @{b}Repeating the task@{ub} Once the main task is underway, regular calls to CheckMessages() mean that the user could start the same task a second time in the same way that they started the first. If for example the task is triggered by clicking on a button, there's nothing to stop the user from clicking the button again and starting a second incarnation of the same task. This may be no problem at all or a complete disaster depending on what the task actually does and exactly how it is coded. If you do not want the task to be able to start multiple times then there are two simple options to prevent it. The main task could disable whichever button or other control it is that launches the task until the task is complete. Alternatively, it might be appropriate to put the window that contains that control to sleep (by calling the @{" SleepPointer " Link SleepPointer} function). Either method will prevent the user from launching the task twice simultaneously. If you do want to be able to launch the task multiple times simultaneously then this can be handled as long as any windows opened by the task and any controls that are created in them are declared locally in the function that launches the task so that each incarnation of the task has it's own copy of those variables. This is illustrated below. In this example, the task is launced from a button whose click function is shown. The following would work: int LaunchTaskButtFn(PushButton *pb) { int i; GuiWindow *TaskWindow = OpenGuiWindow(...); ProgressBar *ProgBar = NULL; if (TaskWindow != NULL) ProgBar = MakeProgressBar(TaskWindow, ...); // long task... for (i = 1; i <= 100; i++) { // Do Task Stuff // ... // Update progress bar if (ProgBar != NULL) SetProgress(ProgBar, i); } if (ProgBar != NULL) DestroyProgressBar(ProgBar, FALSE); if (TaskWindow != NULL) CloseGuiWindow(TaskWindow); return GUI_CONTINUE; } The following would be disastrous: GuiWindow *TaskWindow; ProgressBar *ProgBar; int LaunchTaskButtFn(PushButton *pb) { int i; TaskWindow = OpenGuiWindow(...); ProgBar = NULL; if (TaskWindow != NULL) ProgBar = MakeProgressBar(TaskWindow, ...); // long task... for (i = 1; i <= 100; i++) { // Do Task Stuff // ... // Update progress bar if (ProgBar != NULL) SetProgress(ProgBar, i); } if (ProgBar != NULL) DestroyProgressBar(ProgBar, FALSE); if (TaskWindow != NULL) CloseGuiWindow(TaskWindow); return GUI_CONTINUE; } @{b}Limitations of multi-threading in FoxGui@{ub} The major limitation is that the CheckMessages function will not return until all pending messages have been dealt with. This means that if the user triggers a long process and then starts another long process before the first has finished, the first process will not continue until the second has finished even if the second process contains regular calls to CheckMessages. CheckMessages exists to allow the user to perform short tasks while a long task is underway, not to allow multiple long tasks to progress simultaneously. @endnode @node AddGadget "Adding your own gadgets to FoxGui" Hopefully, FoxGui will one day be able to support bolt-ons so that programmers can build their own gadgets and fully integrate them with FoxGui. I have already laid the ground work for this but the finished product is still some way off. In the mean time I thought it important that you should be able to devise your own intuition gadgets and use them alongside FoxGui gadgets in the same window so I have added the capability to do this but there are two limitations: * FoxGui gadgets can only be created in FoxGui windows. * You cannot manage your own message loop - FoxGui always does that for you. (To my mind this is an advantage rather than a limitation because it saves you, the programmer, a lot of work but no doubt someone will come up with a genuine reason for wanting to handle their own). @{b}So, how do I do it?@{ub} It's easy. There's nothing to stop you from creating your own windows in a FoxGui program - either right at the start (before you call GuiLoop) or in the event function of a gadget (either a FoxGui gadget or one of your own) and of course there's nothing to stop you from creating your own gadgets in these windows. The problem is, since FoxGui handles the message loop for you (in the GuiLoop function) how do you know when an event has occurred that affects one of your gadgets? Well, all you have to do is register your gadget with FoxGui and then, whenever FoxGui receives an IntuiMessage (a message from Intuition) which refers to your gadget, a function that you specify will be called. If you create a gadget in a non-FoxGui window, you register it by calling the @{" RegisterGadget " Link RegisterGadget} function as follows : RegisterGadget(MyGadget, NULL, MyFunction); where MyGadget is a pointer to the gadget (struct Gadget *) and MyFunction is a pointer to a function of your own which will be called whenever something happens to your gadget. The function you specify should have the following prototype : int MyFunction(struct Gadget *gad, struct IntuiMessage *message); The function will be passed a pointer to the gadget in question and a pointer to the actual IntuiMessage that Intuition sent to FoxGui. Please note that because this is the original message (not a copy of it) it is important that you don't change it's contents in any way. It is also @{b}very@{ub} important that you ReplyMsg() the message as soon as you have finished with it exactly as you would normally do if you were handling your own message loop (FoxGui will not do this for you). The function should return either @{" GUI_CONTINUE or GUI_END " Link GuiContinueEnd} which are described in detail elsewhere in this manual. You can register your gadget with FoxGui either before or after adding it to the window (which you can do using the normal intuition function AddGadget). If you want to create a gadget in a FoxGui window you will first need to get a pointer to the Intuition window structure. You do this by calling the function @{" IntuiWindow " Link IntuiWindow} and passing a pointer to the GuiWindow in which you want to create the gadget e.g. struct Window *MyWindow = IntuiWindow(MyGuiWindow); You now have all the information you need to create your intuition gadget and add it to the FoxGui window. Be careful to ensure that it doesn't overlap any other gadgets in the window - if the window is resizable and contains auto-sizing FoxGui gadgets then this will be a problem because at the moment there is no way for your program to find out when a FoxGui window gets resized. Now you need to register your new gadget with FoxGui which you do by calling the @{" RegisterGadget " Link RegisterGadget} function. Unlike registering a gadget in a non-FoxGui window, you also need to pass a pointer to the FoxGui window in which you have placed (or are about to place) the gadget as below: RegisterGadget(MyGadget, MyGuiWindow, MyFunction); When you destroy your gadget (remember that FoxGui won't do that for you) you must call the @{" UnRegisterGadget " Link UnRegisterGadget} function so that FoxGui knows that it doesn't have to deal with it any more. @endnode @node Notice "Important Notice." I make every effort to ensure that if the libraries are used correctly, they will not crash your system or do any other damage. No release is made without first running all of my example FoxGui programs while enforcer and mungwall are checking that the system is clean but for my own protection, I would like to add that: @{i}The author will not be liable for any damage arising from the failure of this program to perform as described, or any destruction of other programs or data residing on a system attempting to run the program. While the author knows of no damaging errors, the user of this program uses it at his or her own risk.@{ui} @endnode @node Introduction "Introduction to FoxGui" @{b}What is FoxGui?@{ub} FoxGui is a library of functions that can be linked into your C programs (and possibly other languages too if you have the know how) to make a whole host of graphical user interface (GUI) objects very quickly and easily. The objects include screens, windows, buttons, list boxes, edit boxes, drop-down list boxes, menus, file requesters and more. You make use of the objects by calling functions to create them. The functions take all of the necessary parameters for you to customise the objects for your application, including pointers to your own functions which will be called when certain events occur. You then call the GuiLoop function which processes all of the events associated with your objects, calling your functions when necessary. Simple. For example, the OpenGuiWindow function opens an intuition window. It takes parameters which specify the size, position and colours of the window, the screen that it will open on, whether or not it is dragable, whether it has a close gadget (and if so, an optional pointer to a function of your own to call when the close gadget is clicked), whether you want a console in the window and many more things besides. The MakeButton function creates a button! The parameters specify the window which the button will appear in, it's size and position, it's colours, a user-defined function to call when the button is clicked, whether this function should be called repeatedly if the button is held down etc etc. Basically, FoxGui is there so that you as an Amiga programmer can spend more time being inventive and less time writing the run-of-the-mill stuff that lives inside every GUI program. All of the functions are supplied in libraries that are linked into your programs at compile time. At some point in the future I will also make them available in a standard Amiga library format. @{b}Why should I use FoxGui?@{ub} Good question. There are other GUI tools available for the Amiga and I guess it really comes down to which one you like. I only have experience of one other (MUI) and I can say without any hesitation that it's main advantage over MUI is speed. It's @{b}much@{ub} faster than MUI but doesn't have quite as many gadgets yet. As for the others? Well, as I say, I haven't used them so I'm not sure. When I started writing this (about four years ago) there weren't so many around, in fact I didn't know of any. To help you decide whether FoxGui is of any use to you, here are some of the things that may distinguish it from other GUIs. * While making use of functions within the latest versions of the Amiga OS where possible, all FoxGui functions operate on any Amiga so if your code needs to be backwards compatible it can be. You compile one program, it works on any Amiga. * Unlike MUI, the user of your programs doesn't need to know anything about the GUI. They don't need anything special installed and don't need to pay to register the GUI. It's completely invisible to them - you link FoxGui.lib to your object code at link time. * It's fast! * It's free! @endnode @node SystemRequirements "FoxGui System Requirements" @{b}FoxGui system requirements@{ub} Because FoxGui is a series of libraries that are linked to your source at compile time, the only thing you need in order to use FoxGui is a development environment of some description. FoxGui is not very memory hungry so the amount of memory required really depends on the size of your application. It's also quite fast so there's no problem running FoxGui applications on an unexpanded A500 (I do this all of the time to ensure that any changes I make are backward compatible). Unfortunately, FoxGui currently also requires the SAS/Lattice libraries lc.lib and lcm.lib to be linked with it. I had hoped to remove this dependancy but haven't had much luck with this so far. I hope to release FoxGui as a DLL in the near future which will overcome this problem. In the meantime, I'm afraid that only SAS/Lattice C users can use it. My apologies. Keep your eye on the Web page for info about future releases (http://www.compulink.co.uk/~teacosy/). See also: @{" Compatibility " Link Compatibility} @endnode @node Compatibility "FoxGui compatibility" @{b}FoxGui compatibility@{ub} I have made every effort to make FoxGui run on every Amiga ever sold but the earliest Amiga I have access to is a late A500 so there may be Amigas out there that FoxGui is incompatible with. This doesn't mean that I have limited FoxGui to what is achievable on an unexpanded A500. FoxGui adapts to the machine that it is run on so that you only have to compile one version of your program and it will work on any Amiga (as long as your code doesn't rely on a later OS)! For example, using FoxGui, drop down list boxes are available on any Amiga but on an A500+ or above, they can get the focus in the same way that edit boxes can. Once they have the focus you can press a key on the keyboard and if there is an entry in the list that starts with that character it will be selected for you. On an A500, the same program would have the same list box containing the same items but the list box cannot get focus so selection can only be performed by clicking the drop button and selecting using the mouse. Limitations of each function and how they differ between Amiga models are included in the @{"functions" Link Functions} section. @endnode @node Format "Format of a FoxGui program" @{b}Format of a FoxGui program@{ub} The best way to describe how to write a FoxGui program is to give a simple example. The code below opens a FoxGui window on a FoxGui screen and asks a question which can be answered by selecting a response from a drop-down list box. The program will then respond in an appropriate manner to your response. You can exit the program at any time by pressing the Okay button in the window or by clicking the window's close gadget. The code is heavily commented so that you can hopefully understand what is going on. Assuming you have reasonable knowledge of C, you should find it very simple. #include "FoxGui.h" GuiScreen *GreetingsScreen = NULL; GuiWindow *GreetingsWindow = NULL; int OkayButtFn(PushButton *pb) { /* @{i}We only have one button in our application so we don't need to check which one has been clicked. We want the Okay button to quit the program so all we have to do is return GUI_END and this will cause GuiLoop() to return. Our code at the end of the main() function (after the call to GuiLoop) will then clear everything up for us. @{ui}*/ return GUI_END; } int GreetingsWinCloseFn(GuiWindow *win) { /* @{i}We only have one window. The fact that this function has been called means that it's close gadget has been clicked and because we have a close gadget function (this function) we are responsible for closing the window. However, we want the close gadget function to actually end the program so rather than closing the window here, we'll just return GUI_END (to cause GuiLoop() to exit) and our cleanup code at the end of the main() function will close this window as well as the screen. @{ui}*/ return GUI_END; } BOOL ResponseBoxFn(DDListBox *lb) { /* @{i}GetDDListBoxText returns a pointer to the actual buffer used by the drop-down list box so we mustn't change it directly but it's okay to look at it! @{ui}*/ char *response = GetDDListBoxText(lb); /* @{i}Fortunately, all of our entries in the list box begin with different letters so instead of using strcmp() to work out what has been selected, we can just look at the first letter of the text in the drop-down list box. @{ui}*/ switch (response[0]) { case 'F': // "Fine thanks." /* @{i}The GuiMessage function displays a modal message to the user. Modal means that the user won't be able to access any gadgets on other windows or screens in this application until they have responded to the message which they can do either by clicking on the Okay button or by pressing the O or return keys which are hot-keys for the button. @{ui}*/ GuiMessage(GreetingsScreen, "I'm glad to hear it.", "FoxGui", 2, 1, 2, 0, GM_OKAY); break; case 'T': // "Terrible!" GuiMessage(GreetingsScreen, "I'm sorry to hear that!", "FoxGui", 2, 1, 2, 0, GM_OKAY); break; case 'N': // "None of your business!" GuiMessage(GreetingsScreen, "Well there's no need to be rude!", "FoxGui", 2, 1, 2, 0, GM_OKAY); } return TRUE; } /* @{i}This function closes all of the things that we opened in main() to free up the memory and other system resources because our program is about to exit. @{ui}*/ static int CloseDown(int retval) { if (GreetingsWindow) { /* @{i}ResponseBox is declared in main() so we don't have a pointer to it here and so we can't use the DestroyDDListBox() function. However, we can destroy it by calling DestroyWinDDListBoxes() with a pointer to our window. That will destroy any drop-down list boxes in that window and is actually much more convenient because it saves us from checking whether the drop-down list box was created successfully in the first place (this function will be called if the MakeDDListBox() function in main() fails). Exactly the same is true of our button (OkayButton) so we use the DestroyWinButtons() function instead of the DestroyButton() function. @{ui}*/ DestroyWinDDListBoxes(GreetingsWindow, FALSE); DestroyWinButtons(GreetingsWindow, FALSE); /* @{i}Close the window we created in the main() function. @{ui}*/ CloseGuiWindow(GreetingsWindow); } /* @{i}Close our screen (if it opened successfully). @{ui}*/ if (GreetingsScreen) CloseGuiScreen(GreetingsScreen); /* @{i}Free up all resources used by the Gui @{ui}*/ EndGui(); return retval; } int main(void) { DDListBox *ResponseBox = NULL; PushButton *OkayButton = NULL; /* @{i}Initialise FoxGui. It is essential that this is done before any other calls are made to FoxGui functions. It is highly unlikely to fail (as are most of the other functions used here as long as the parameters supplied are sensible) but notice that I check for failure just in case. @{ui}*/ if (!(InitGui(FAST_MALLOCS, NULL))) return 1; /* @{i}Open a GuiScreen to run our application on. We'll just give it two bitplanes which allows four colours - plenty for such a simple program. @{ui}*/ if ((GreetingsScreen = OpenGuiScreen(2, 2, 1, NULL, "Welcome to FoxGui", NULL, 0)) == NULL) return CloseDown(1); /* @{i}Open the GuiWindow to create our controls in. By supplying the GW_CLOSE parameter we ensure that the window has a close gadget and by supplying a pointer to our GreetingsWinCloseFn() (defined above) we ensure that if the user clicks the close gadget, FoxGui won't just close the window for us but will call our function instead and do what ever our function tells it to do! @{ui}*/ if ((GreetingsWindow = OpenGuiWindow(GreetingsScreen, 100, 40, 400, 100, 0, 0, 2, 1, 0, "Greetings!", GW_DRAG | GW_CLOSE, GreetingsWinCloseFn)) == NULL) return CloseDown(1); /* @{i}Make the drop-down list box that the user will use to select a response to the question. Notice that I've specified the question itself (How are you today?) as the PreText for the drop- down list. There are many other ways I could have done this (using an output box or using a console and writing text directly to the window or even by bypassing FoxGui altogether and allocating my own IntuiText and writing it to the window's rastport) but since I wanted the text to be to the left of the list box, this was by far the easiest method. We'll add the possible responses into the list box in a moment. @{ui}*/ if ((ResponseBox = MakeDDListBox(GreetingsWindow, 160, 30, 190, 22, 3, 1, 0, 1, 0, "How are you today?", NULL, ResponseBoxFn, THREED)) == NULL) return CloseDown(1); /* @{i}Make the Okay button which the user can click to quit the application. Notice that we pass a pointer to our OkayButtFn() defined above which will get called when the user clicks the okay button. Notice also that I've set the hot-key to 'O' and underlined the O of Okay so that the user knows what the hot-key is. I've also passed the BN_OKAY flag to tell FoxGui to allow the return key as an extra hot-key for this button. @{ui}*/ if ((OkayButton = MakeButton(GreetingsWindow, "_Okay", 170, 80, 60, 14, 1, 0, 'O', NULL, OkayButtFn, BN_CLEAR | BN_STD | BN_OKAY)) == NULL) return CloseDown(1); /* @{i}Add the three possible responses to our drop-down list box. @{ui}*/ AddToDDListBox(ResponseBox, "Fine thanks"); AddToDDListBox(ResponseBox, "Terrible!"); AddToDDListBox(ResponseBox, "None of your business!"); GuiLoop(); /* @{i}It is important to free up any memory we have used by destroying all of the FoxGui gadgets we have created. All of this is done in the CloseDown() function. @{ui}*/ return CloseDown(0); } @endnode @node Suggestions "Suggestions?" @{b}Suggestions?@{ub} If you have any suggestions for improvements you would like to see in the next release of FoxGui, or if you have any other need to contact me I can be reached at FoxySoft@teacosy.compulink.co.uk. Please don't expect immediate replies as I'm usually too busy improving FoxGui to actually check my mail! I will get back to you as soon as I can. Also, keep an eye on the web page. Details of forthcoming releases and improvements that are planned are listed there: http://www.compulink.co.uk/~teacosy/ @endnode @node Bugs "FoxGui Bugs" @{b}Bugs in the current release of FoxGui@{ub} The following minor problems are known to exist in the current release. No major problems are known but if you find any, please Email me at: FoxySoft@teacosy.compulink.co.uk * FoxGui.lib currently needs to be linked to your programs along with the lc.lib and lcm.lib which come with versions of Lattice or SAS C. I have tried to remove the dependancy on the maths library but have come up against all sorts of unexpected problems. I hope to release FoxGui as a DLL soon which will overcome these problems - in the meantime, only users of SAS or Lattice C will be able to use it. Sorry. Keep your eye on the Web page for info about future releases (http://www.compulink.co.uk/~teacosy/). @endnode @node WishList "FoxGui Wish list" @{b}What's next for FoxGui@{ub} There is still much that can be done to improve FoxGui. There are plenty of things that I intend to implement as soon as I get time and just so that you know what's coming soon, I've outlined them below. They are in approximate order of importance but subject to change. * Make a runtime library (DLL) version. * Support for multiple threads in one FoxGui app. * A treeview control. * A C++ O/O interface to all objects. @endnode @node Functions "FoxGui functions" @{b} FoxGui Functions@{ub} Since there are rather a lot of FoxGui functions, I have broken them down into sections divided by the object which they affect. Each section contains a description of the object type and full descriptions of each function available for objects of that type :- @{" Screens " Link Screens} @{" Windows " Link Windows} @{" Menus " Link Menus} @{" Tab controls " Link TabControls} @{" Frames " Link Frames} @{" Buttons " Link Buttons} @{" Boolean gadgets " Link BoolGads} @{" Edit boxes " Link EditBoxes} @{" List boxes " Link ListBoxes} @{" Drop-down list boxes " Link DDListBoxes} @{" Output boxes " Link OutputBoxes} @{" Timers " Link Timers} @{" Progress Bars " Link ProgressBars} @{" Images " Link Images} @{" Miscelaneous " Link Misc} @{" Complete list of prototypes " Link ProtoList} @endnode @node Images "FoxGui Image functions" Foxgui has a number of functions for manipulating ILBM images. Any ILBM image can be loaded, shown in a FoxGui window, attached to a button or frame etc. All of the image functions require IFFparse.library. Two versions of IFFparse.library are available - one will have been on your workbench disk if you bought a V39 Amiga (e.g. an Amiga 1200) which only works on Amigas with V39 and above. The other works on @{b}all@{ub} Amigas all the way back to an A500 with workbench 1.3 but was only supplied with Amigas from V37 onwards so if you have an older Amiga then you will need to get hold of that version. Unfortunately I don't have a license to distribute it so I can't supply it with FoxGui but you may find that you already have it supplied with some other piece of software. If you make use of the FoxGui image functions in your code and someone attempts to run the code on an Amiga without IFFparse library, the program won't fail or crash or do anything nasty - the user just won't see your images. The following image functions are currently available :- @{" LoadBitMap " Link LoadBitMap} @{" ShowBitMap " Link ShowBitMap} @{" HideBitMap " Link HideBitMap} @{" FreeGuiBitMap " Link FreeGuiBitMap} @{" ScaleBitMap " Link ScaleBitMap} @{" RedrawBitMap " Link RedrawBitMap} @{" AttachBitMapToControl " Link AttachBitMapToControl} @{" ScreenColoursFromILBM " Link ScreenColoursFromILBM} @endnode @node LoadBitMap "LoadBitMap function" Function prototype: GuiBitMap *LoadBitMap(char *fname); Description: Loads an ILBM image with the specified path and filename and returns a GuiBitMap structure which can be passed as a parameter to other FoxGui image functions. Parameters: fname: The full or relative path and filename of the ILBM image to load. Returns: If successful, a pointer to a GuiBitMap structure containing the image loaded, otherwise NULL. This function will fail if the IFFparse library could not be opened. Known bugs: None. See also: @{" ShowBitMap " Link ShowBitMap} @{" HideBitMap " Link HideBitMap} @{" FreeGuiBitMap " Link FreeGuiBitMap} @{" ScaleBitMap " Link ScaleBitMap} @{" RedrawBitMap " Link RedrawBitMap} @{" AttachBitMapToControl " Link AttachBitMapToControl} @{" ScreenColoursFromILBM " Link ScreenColoursFromILBM} @endnode @node ShowBitMap "ShowBitMap function" Function prototype: BitMapInstance *ShowBitMap(GuiBitMap *bm, GuiWindow *w, unsigned short x, unsigned short y, short flags); Description: Displays a previously loaded image in a FoxGui window. Note that the image won't look as it was intended to unless your screen is deep enough to show the correct number of colours for the image and the screen's pallette matches the images pallette (see @{" ScreenColoursFromILBM " Link ScreenColoursFromILBM} and @{" OpenGuiScreen " Link OpenGuiScreen}). Parameters: bm: A pointer to a GuiBitMap structure as returned by the @{" LoadBitMap " Link LoadBitMap} function. w: A pointer to the FoxGui window in which to display the image. x, y: The coordinates (in pixels) within the window for the top left hand corner of the image. flags: The only flag currently available for this function is BM_OVERLAY. If this is specified, any pixels within the image which don't contain any data (i.e. are transparent) won't be drawn. This allows an image to be shown over the top of another and the bottom image to be seen "through" the top one where it is transparent. If this flag is not specified then every pixel in the image will be drawn so anything currently drawn in the window will be overwritten if it falls within the bounds of the image. Returns: If successful, a pointer to a BitMapInstance is returned. Keep a copy of this - you will need it to free the memory used by the image or to hide or refresh it. Known bugs: None. See also: @{" LoadBitMap " Link LoadBitMap} @{" HideBitMap " Link HideBitMap} @{" FreeGuiBitMap " Link FreeGuiBitMap} @{" ScaleBitMap " Link ScaleBitMap} @{" RedrawBitMap " Link RedrawBitMap} @{" AttachBitMapToControl " Link AttachBitMapToControl} @{" ScreenColoursFromILBM " Link ScreenColoursFromILBM} @endnode @node HideBitMap "HideBitMap function" Function prototype: BOOL HideBitMap(BitMapInstance *bmi); Description: Hides an image previously displayed in a window with the @{" ShowBitMap " Link ShowBitMap} function and free's the memory used by the BitMapInstance. You should never refer to a BitMapInstance when it has been hidden as that memory will have been free'd - if you show the image again (using ShowBitMap) you will be given a new BitMapInstance. If the image was shown on top of other images as an overlay, you will need to refresh the other images using @{" RedrawBitMap " Link RedrawBitMap}. Parameters: bmi: A pointer to the BitMapInstance returned by ShowBitMap when the image was drawn. Returns: TRUE if the image was successfully hidden, FALSE otherwise. Known bugs: None. See also: @{" LoadBitMap " Link LoadBitMap} @{" ShowBitMap " Link ShowBitMap} @{" FreeGuiBitMap " Link FreeGuiBitMap} @{" ScaleBitMap " Link ScaleBitMap} @{" RedrawBitMap " Link RedrawBitMap} @{" AttachBitMapToControl " Link AttachBitMapToControl} @{" ScreenColoursFromILBM " Link ScreenColoursFromILBM} @endnode @node FreeGuiBitMap "FreeGuiBitMap function" Function prototype: BOOL FreeGuiBitMap(GuiBitMap *bm); Description: This function free's the memory used by an image that was loaded with the @{" LoadBitMap " Link LoadBitMap} function. You should not free a GuiBitMap while it is displayed (other than attached to a control). Only call this function when you have completely finished with the image. Parameters: bm: A pointer to the GuiBitMap as returned by the LoadBitMap function. Returns: TRUE if the image was successfully free'd. FALSE otherwise. Known bugs: None. See also: @{" LoadBitMap " Link LoadBitMap} @{" ShowBitMap " Link ShowBitMap} @{" HideBitMap " Link HideBitMap} @{" ScaleBitMap " Link ScaleBitMap} @{" RedrawBitMap " Link RedrawBitMap} @{" AttachBitMapToControl " Link AttachBitMapToControl} @{" ScreenColoursFromILBM " Link ScreenColoursFromILBM} @endnode @node ScaleBitMap "ScaleBitMap function" Function prototype: GuiBitMap *ScaleBitMap(GuiBitMap *source, unsigned short destwidth, unsigned short destheight); Description: Scales an image loaded with @{" LoadBitMap " Link LoadBitMap} to the size specified. Note that this function requires graphics library V36 or above and will fail when used on V35 or below. Parameters: source: A pointer to a GuiBitMap to scale. destwidth: The target width in pixels of the scaled image. destheight: The target height in pixels of the scaled image. Returns: If successful, a pointer to a new GuiBitMap is returned which is a scaled version of the one supplied. Note that if the original image is not displayed or attached to a control then the original need not be kept after calling this function (i.e. you can free it with a call to @{" FreeGuiBitMap " Link FreeGuiBitMap}). NULL is returned if this function fails. Known bugs: None. See also: @{" LoadBitMap " Link LoadBitMap} @{" ShowBitMap " Link ShowBitMap} @{" HideBitMap " Link HideBitMap} @{" FreeGuiBitMap " Link FreeGuiBitMap} @{" RedrawBitMap " Link RedrawBitMap} @{" AttachBitMapToControl " Link AttachBitMapToControl} @{" ScreenColoursFromILBM " Link ScreenColoursFromILBM} @endnode @node RedrawBitMap "RedrawBitMap function" Function prototype: BOOL RedrawBitMap(BitMapInstance *bmi); Description: Redraws the BitMapInstance supplied. If the image was originally drawn as an overlay then the refresh will also draw it as an overlay. Parameters: A pointer to a BitMapInstance as returned by @{" ShowBitMap " Link ShowBitMap}. Returns: TRUE if successful, FALSE otherwise. Known bugs: None. See also: @{" LoadBitMap " Link LoadBitMap} @{" ShowBitMap " Link ShowBitMap} @{" HideBitMap " Link HideBitMap} @{" FreeGuiBitMap " Link FreeGuiBitMap} @{" ScaleBitMap " Link ScaleBitMap} @{" AttachBitMapToControl " Link AttachBitMapToControl} @{" ScreenColoursFromILBM " Link ScreenColoursFromILBM} @endnode @node AttachBitMapToControl "AttachBitMapToControl function" Function prototype: BOOL AttachBitMapToControl(GuiBitMap *bm, void *control, short left, short top, short width, short height, int flags); Description: Attaches an image (as loaded with @{" LoadBitMap " Link LoadBitMap}) or part of an image to a FoxGui button or frame. Many images can be attached to the same control with multiple calls to this function. Parameters: bm: A pointer to the GuiBitMap image to attach to the control. Note that a copy is made of the required portion of the image so there is no need to maintain the original after calling this function if it is not needed elsewhere. control: A pointer to a FoxGui frame or button to which to attach the image. left, top, width, height: These specify the portion of the image to attach to the control. left and top specify the coordinates within the image of the top left corner of the portion of the image to attach to the control. width and height specify the width and height of the portion that you want to attach (in pixels). width or height can be set to -1 which means the rest of the width/height of the image. For example, to attach the whole image to the control, specify left, top, width and height as 0, 0, -1 and -1 respectively. To attach all of the image except the top 5 rows and the left 3 columns, specify 3, 5, -1, -1. flags: The following flags are available :- BM_OVERLAY, BM_SCALE, BM_CLIP, BM_SMART and BM_STUPID. BM_OVERLAY causes the image to be over-laid onto the control. This means that any pixels in the image which are transparent won't get drawn, allowing several images to be attached to the same control and to be transparent. BM_SCALE causes the image to be scaled to fit the control but only works on Amigas with graphics library version 36 or above. On Amigas with graphics library version 35 or below, BM_SCALE is ignored and BM_CLIP is used instead. BM_CLIP is the opposite of BM_SCALE and is the default if neither is specified. BM_CLIP causes the image to be clipped to fit the control. BM_SMART can be used when attaching images to controls which have the S_AUTO_SIZE flag set. It causes an extra copy of the image to be kept so that if a window containing the control is resized (causing the control to resize), the image attached to the control will be re-clipped or re-scaled (depending upon whether BM_CLIP or BM_SCALE was specified) from the original. BM_STUPID is the opposite of BM_SMART and is the default if neither is specified. When a BM_STUPID control is resized, the image will still be re-clipped or re-scaled but from the image currently shown on the control - not from the original. The result is that if a control containing a clipped image gets larger, no extra will be shown or if the image is scaled, repeated re-scaling of the image will cause quite rapid loss of definition because each rescale will be done from the previously scaled version. If BM_SMART is specified when attaching an image to a control which doesn't have the S_AUTO_SIZE flag set (and hence will never change size) it is ignored and BM_STUPID is used instead. The advantage of BM_SMART is obvious. The advantage of BM_STUPID is that it requires less memory. Returns: TRUE for success, FALSE for failure. Known bugs: None. See also: @{" LoadBitMap " Link LoadBitMap} @{" ShowBitMap " Link ShowBitMap} @{" HideBitMap " Link HideBitMap} @{" FreeGuiBitMap " Link FreeGuiBitMap} @{" ScaleBitMap " Link ScaleBitMap} @{" RedrawBitMap " Link RedrawBitMap} @{" ScreenColoursFromILBM " Link ScreenColoursFromILBM} @endnode @node ScreenColoursFromILBM "ScreenColoursFromILBM function" Function prototype: BOOL ScreenColoursFromILBM(GuiScreen *sc, char *fname); Description: Modifies the pallette of an open FoxGui screen to match the pallette of the ILBM image whose filename is specified. Useful for applications such as slideshow viewers where it will be necessary to constantly review the pallette to match each slide. Note that this function will affect everything displayed on the screen and will spoil the 3D effect of any controls on the screen unless the shine and shadow pens in the image happen to match those used for the screen. This function attempts to set the shine and shadow pens to sensible colours by calling @{" SetGuiPens " Link SetGuiPens} but it's not currently very clever so you may have to call the function again yourself afterwards. Also note that SetGuiPens doesn't redraw any existing controls so if you're going to call ScreenColoursFromILBM it's best to do it before drawing any controls. Parameters: sc: A pointer to an open FoxGui screen. fname: The filename of an ILBM image whose pallette is to be copied. Returns: TRUE for success, FALSE for failure. Note that this function will fail if the screen isn't deep enough for the number of colours in the images pallette. Known bugs: None. See also: @{" LoadBitMap " Link LoadBitMap} @endnode @node ProgressBars "FoxGui Progress Bar functions" Progress bars are indicators to display how far through a process you are. Usually, when an application is busy it will change the pointer for it's window to a stop-clock so that the user knows it's busy. If it's busy doing something that will take a long time, it's polite to show the user how much progress is being made so that he knows the machine hasn't crashed and whether he's got time to go and make a cup of tea (or even have a nights sleep) before the application is ready for input again. This is what progress bars are for. Typically they consist of a long, thin rectangular frame which gradually gets filled in a different colour to show progress. When the frame is full, the processing has finished and the user can gain some idea of how long he has to wait by how full the progress bar is. The following progress bar functions are currently available :- @{" DestroyProgressBar " Link DestroyProgressBar} @{" MakeProgressBar " Link MakeProgressBar} @{" SetProgress " Link SetProgress} @{" SetProgressMax " Link SetProgressMax} @endnode @node DestroyProgressBar "DestroyProgressBar function" Function prototype: void DestroyProgressBar(ProgressBar *pb, BOOL refresh); Description: Destroy the specified FoxGui progress bar and free all associated resources. Parameters: pb: A pointer to the FoxGui progress bar to destroy. refresh: If TRUE, the progress bar will disappear from the window. Set this to FALSE only if you are about to close the window - in which case refreshing the window would be pointless. Known bugs: None. See also: @{" Destroy " Link Destroy} @{" MakeProgressBar " Link MakeProgressBar} @endnode @node MakeProgressBar "MakeProgressBar function" Function prototype: ProgressBar *MakeProgressBar(void *Parent, int left, int top, int width, int height, short fillcol, int tcol, short flags); Description: Make a new progress bar in the specified FoxGui window or frame. The progress indicator will initially be set to zero. Parameters: Parent: A pointer to a FoxGui window or frame in which to make the progress bar. left: The offset of the left edge of the progress bar (in pixels) from the left edge of the window/frame. top: The offset of the top edge of the progress bar (in pixels) from the top edge of the window/frame. width: The width of the progress bar in pixels. height: The height of the progress bar in pixels. fillcol: The colour in which to fill the progress bar to indicate progress. tcol: The colour for the text. Progress bars also show textually the amount of progress that has been made. The position of the text is determined by the flags. flags: The currently available flags are :- PB_RAISED, PB_INSET : These specify whether the progress bar appears rased from or inset into the screen. The default is raised if neither is specified. PB_CAPTION_CENTRE, PB_CAPTION_TOP_LEFT, PB_CAPTION_BOTTOM_LEFT, PB_CAPTION_TOP_RIGHT, PB_CAPTION_BOTTOM_RIGHT : These specify the position of the caption which can go above or below and left or right of the progress bar or can even go right in the middle of the bar. If you want the text in the middle, you should make sure that tcol and fillcol are not the same colour. If none of these is specified then the default is top right. PB_FILL_LR, PB_FILL_BT : These specify whether the progress bar should fill from the left towards the right or from the bottom upwards. The default is left to right. @{" S_AUTO_SIZE " Link S_AUTO_SIZE} Returns: If successful, a pointer to a new progress bar is returned. If not, NULL is returned. Known bugs: None. See also: @{" DestroyProgressBar " Link DestroyProgressBar} @{" SetProgress " Link SetProgress} @{" SetProgressMax " Link SetProgressMax} @endnode @node SetProgress "SetProgress function" Function prototype: void SetProgress(ProgressBar *pb, int progress); Description: Sets the current amount of progress for the specified progress bar. Parameters: pb: A pointer to a progress bar to update. progress: The amount of progress that has been made. This should be between zero and the maximum progress amount for the progress bar. The maximum is generally 100 so that progress is shown as a percentage but it can be set to anything you like by calling @{" SetProgressMax " Link SetProgressMax}. Known bugs: None. See also: @{" MakeProgressBar " Link MakeProgressBar} @{" SetProgressMax " Link SetProgressMax} @endnode @node SetProgressMax "SetProgressMax function" Function prototype: void SetProgressMax(ProgressBar *pb, int progressmax); Description: Set the maximum for a progress bar. By default, progress bars show progress as a percentage so you can call @{" SetProgress " Link SetProgress} with any number between 0 and 100. This is not always useful, however. For example, let's take the case of an internet browser which downloads messages from news groups and has to put them in your local database. It could use a progress bar to show progress in adding them to the database. If the progress bar went from 0 to 100, the programmer would need to work out, after processing each message, what percentage of messages had been processed and then set the progress bar accordingly. It would be much easier, however, to use this function to set the maximum to the number of messages downloaded and then just add one to the progress indicator after processing each message. Parameters: pb: A pointer to the progress bar to modify. progressmax: The maximum for the progress bar. Known bugs: None. See also: @{" MakeProgressBar " Link MakeProgressBar} @{" SetProgress " Link SetProgress} @endnode @node Frames "FoxGui Frame functions" Frames are rather like buttons in that they look like buttons and that if you click on them, they perform a function which you define. Like buttons they can also have images attached to them (drawn on them) - see @{" AttachBitMapToControl " Link AttachBitMapToControl} and they can be hidden or shown at will. Unlike buttons, however, frames can also respond to right mouse button clicks. Frames are also rather like windows in that controls can be created within them. When you create a control, one of the parameters to the function is a pointer to a window in which to create the control. Instead of passing a pointer to a window you can now pass a pointer to a frame if you prefer. The control will be created inside the frame, offset from the top left hand corner by the "left" and "top" parameters you specify. The advantage of creating controls in frames is that a group of associated controls can be created in the same frame which gives a border around the group and shows visually that they are associated with each other. (Of course, frames do not have to have a border if you don't want one). Another advantage is that if you then want to hide a whole group of controls in the same frame, you can just hide the frame - all of the controls within it will become hidden too! In the future, I also intend for you to be able to drag and drop frames (although you will be able to decide whether a particular frame can be dragged and dropped when you create it). For the time being though, the following frame functions are available :- @{" DestroyAllFrames " Link DestroyAllFrames} @{" DestroyFrame " Link DestroyFrame} @{" DestroyWinFrames " Link DestroyWinFrames} @{" HideFrame " Link HideFrame} @{" MakeFrame " Link MakeFrame} @{" ShowFrame " Link ShowFrame} @endnode @node DestroyAllFrames "DestroyAllFrames function" Function prototype: void DestroyAllFrames(BOOL refresh); Description: Destroy all FoxGui frames created by this application, freeing all resources. Parameters: refresh: If TRUE, the frames will disappear (i.e. their imagery will be removed from the windows they were made in). You would typically set this to FALSE only if you were about to close the window anyway (there's no point in updating the imagery for a window which is about to close since closing the window will remove the imagery). Known bugs: None. See also: @{" DestroyFrame " Link DestroyFrame} @{" DestroyWinFrames " Link DestroyWinFrames} @{" HideFrame " Link HideFrame} @{" MakeFrame " Link MakeFrame} @endnode @node DestroyFrame "DestroyFrame function" Function prototype: void DestroyFrame(Frame *Fptr, BOOL refresh); Description: Destroy the specified frame, freeing it's resources. Parameters: Fptr: A pointer to the frame to destroy. refresh: If TRUE, the frame will disappear (i.e. it's imagery will be removed from the window it was made in). You would typically set this to FALSE only if you were about to close the window anyway (there's no point in updating the imagery for a window which is about to close since closing the window will remove the imagery). Known bugs: None. See also: @{" Destroy " Link Destroy} @{" DestroyAllFrames " Link DestroyAllFrames} @{" DestroyWinFrames " Link DestroyWinFrames} @{" HideFrame " Link HideFrame} @{" MakeFrame " Link MakeFrame} @endnode @node DestroyWinFrames "DestroyWinFrames function" Function prototype: void DestroyWinFrames(GuiWindow *w, BOOL refresh); Description: Destroy all frames in the specified window. Parameters: w: A pointer to the Gui window whose frames are to be destroyed. refresh: If TRUE, the frames will disappear (i.e. their imagery will be removed from the window). You would typically set this to FALSE only if you were about to close the window anyway (there's no point in updating the imagery for a window which is about to close since closing the window will remove the imagery). Known bugs: None. See also: @{" DestroyAllFrames " Link DestroyAllFrames} @{" DestroyFrame " Link DestroyFrame} @{" HideFrame " Link HideFrame} @{" MakeFrame " Link MakeFrame} @endnode @node HideFrame "HideFrame function" Function prototype: void HideFrame(Frame *Fptr); Description: Hides the specified frame, making it invisible to the user so that the user cannot interact with it in any way but without freeing the resources so that it can quickly be shown again at any time by calling the @{" ShowFrame " Link ShowFrame} function. Parameters: Fptr: A pointer to the FoxGui frame to hide. Known bugs: None. See also: @{" DestroyFrame " Link DestroyFrame} @{" MakeFrame " Link MakeFrame} @{" ShowFrame " Link ShowFrame} @endnode @node MakeFrame "MakeFrame function" Function prototype: Frame *MakeFrame(void *Parent, char *name, int left, int top, int width, int height, int tcol, int bcol, struct Border *cb, int (*callfn) (Frame*, short, short, short, void**), short flags, ...); Description: Make a new FoxGui frame in the specified FoxGui window or frame. Parameters: Parent, left, top, width, height, tcol, bcol, cb: These parameters are identical to the similarly named parameters of @{" MakeButton " Link MakeButton}. name: As with MakeButton, this should be a pointer to a NULL terminated text string to use as a caption for the frame. If you do not want a caption you should use "" or NULL. Unlike buttons however, frames cannot have hot-keys and so you cannot use the "_" character to indicate a character in the caption to underline. You can of course use the "_" character in your frame caption - it just won't act the way it does for buttons. If the caption for the frame is too long to fit in the frame it will be truncated to fit - the caption will never extend beyond the frame border. If the frame gets resized (due to a window being resized) then more of the caption may become visible - i.e. FoxGui remembers the whole caption not just the visible bit. callfn: A pointer to a function to call when the user clicks on your frame with the left or right mouse button or data is dragged into or out of this frame (depending on which flags are specified). The function should have the following prototype :- int MyFrameFn(Frame *Fm, short Event, short x, short y, void **DragData); Fm will be a pointer to the frame which was clicked/dragged by the user. Event will have one of the values FM_LBUT, FM_RBUT, FM_DRAG or FM_DROP depending on whether the left or right mouse button was clicked or data was dragged out of or dropped into the frame respectively. x and y will contain the coordinates of the exact position of the mouse event (left click, right click, drag or drop) relative to the top, left hand corner of the frame. DragData is NULL unless the Event is FM_DRAG or FM_DROP. If the user is dragging this frame then you will probably want to store a pointer to the data that's being dragged somewhere where it can easily be found by the control that the data is eventually dropped in. The data can be anything you want. DragData is a pointer to a pointer that you can modify to point to whatever piece of data it is that the user is dragging. Let's take a simple example - you have an application with two frames and you want to be able to drag the name of either frame to the other. Your event function for one of your frames might look like this: int FirstFrameFn(Frame *Fm, short Event, short x, short y, void **DragData) { if (Event == FM_DRAG) { /* The user is dragging the name of this frame to another control (or maybe to itself!). Set DragData to point to a constant text string containing the name of this frame (Frame1). */ *DragData = "Frame1"; } else if (Event == FM_DROP) { /* The user has dropped something in this frame. Let's tell the user what has been dropped and where! */ char Message[100]; sprintf(message, "%s was dropped in Frame1 at (%d, %d)", *DragData, x, y); GuiMessage(MyScreen, Message, "Drop!", 1, 2, 6, 5, GM_OKAY); } return GUI_CONTINUE; } As you can see from the function above, it is actually *DragData that you set and use - DragData is a pointer to a pointer that you can modify. See the notes in the @{" Drag/Drop functionality " Link DragDropFunc} section for more information about drag and drop event functions. Your function should return either @{" GUI_END " Link GuiContinueEnd} or @{" GUI_CONTINUE " Link GuiContinueEnd}. flags: The following flags are available: FM_LBUT, FM_RBUT, @{" S_AUTO_SIZE " Link S_AUTO_SIZE}, FM_CLEAR, FM_DRAG, FM_DRAGIMAGE and FM_DROP. FM_LBUT causes the frame to respond to left button clicks and FM_RBUT causes it to respond to right button clicks. FM_CLEAR is the same as the BN_CLEAR flag for buttons (see @{" MakeButton " Link MakeButton}). The FM_DRAG flag indicates that the user will be able to drag data from this frame into other drag/drop aware controls and the FM_DROP flag indicates that the user will be able to drag data into this control from other drag/drop aware controls. You should specify the FM_DRAGIMAGE flag if you wish to supply your own drag/drop mouse pointer to use instead of the standard FoxGui one when dragging data from this control into others. If you specify the FM_DRAGIMAGE flag, you should also pass the following extra parameters to the MakeFrame function. Extra parameters for the FM_DRAGIMAGE flag: unsigned short *DragPointer: A pointer to an array of numbers making up a standard Intuition sprite data structure. This must be stored in chip memory since it is to be used as a mouse pointer. int Width: The width in pixels of the pointer provided. The maximum width of an Amiga mouse pointer is 16 pixels. int Height: The height in pixels of the pointer provided. There is no maximum height. int XOffset: int YOffset: These two numbers specify the offset of the pointers hot-spot from the top left corner of the sprite. They are typically zero or negative. Returns: If successful, a pointer to a new FoxGui frame. Known bugs: None. See also: @{" Drag/Drop functionality " Link DragDropFunc} @{" DestroyFrame " Link DestroyFrame} @{" HideFrame " Link HideFrame} @{" AttachBitMapToControl " Link AttachBitMapToControl} @endnode @node ShowFrame "ShowFrame function" Function prototype: void ShowFrame(Frame *Fptr); Description: Show the specified hidden FoxGui frame (see @{" HideFrame " Link HideFrame}). Parameters: Fptr: A pointer to a hidden FoxGui frame to show. Known bugs: None. See also: @{" HideFrame " Link HideFrame} @{" MakeFrame " Link MakeFrame} @endnode @node Timers "FoxGui Timer functions" Timer controls allow your program to perform tasks at regular intervals (every second or every minute). You do this by creating a timer using the @{" MakeTimer " Link MakeTimer} function which you supply with a pointer to a function that you want to be called and a flag specifying whether you want it called every second or every minute. The timer will not be active (and will not call your function) until you start it with the @{" StartTimer " Link StartTimer} function and will not stop until you call either the @{" StopTimer " Link StopTimer} or @{" PauseTimer " Link PauseTimer} function. If your timer function is to be called every second then it's vital to make sure that the code in your function returns as fast as possible so as not to cause your Amiga to grind to a halt under the strain and if your function takes over a second to run then it will not be called again for the second that was missed during your functions execution. If your timer is only going to trigger your function once a minute then these issues won't apply. Always destroy a timer (using @{" DestroyTimer " Link DestroyTimer}) when you've finished with it so that it doesn't continue to use up valuable processing time. The following Timer functions are currently available :- @{" AddTime " Link AddTime} @{" DestroyAllTimers " Link DestroyAllTimers} @{" DestroyTimer " Link DestroyTimer} @{" MakeTimer " Link MakeTimer} @{" PauseTimer " Link PauseTimer} @{" SetTime " Link SetTime} @{" StartTimer " Link StartTimer} @{" StopTimer " Link StopTimer} @{" UnpauseTimer " Link UnpauseTimer} @endnode @node AddTime "AddTime function" Function prototype: void AddTime(Timer *t, long secs); Description: Adds a specified number of seconds to the running time of the specified timer. For example, if timer T had been runnning for 10 seconds when you called AddTime(T, 50) then it would now behave exactly as if it had been running for 1 minute. Parameters: t: The timer whose time is to be modified. secs: The number of seconds to add to timer t. Note that this can be a negative number if you wish to subtract time. Known bugs: None. See also: @{" DestroyTimer " Link DestroyTimer} @{" MakeTimer " Link MakeTimer} @{" PauseTimer " Link PauseTimer} @{" SetTime " Link SetTime} @{" StartTimer " Link StartTimer} @{" StopTimer " Link StopTimer} @{" UnpauseTimer " Link UnpauseTimer} @endnode @node DestroyAllTimers "DestroyAllTimers function" Function prototype: void DestroyAllTimers(void); Description: Destroys all timers created by the current application, freeing all associated resources. Known bugs: None. See also: @{" DestroyTimer " Link DestroyTimer} @{" MakeTimer " Link MakeTimer} @endnode @node DestroyTimer "DestroyTimer function" Function prototype: BOOL DestroyTimer(Timer *t); Description: Destroys the specified timer control, freeing all associated resources. Parameters: t: A pointer to the timer to destroy. Returns: TRUE if successful, FALSE otherwise. Known bugs: None. See also: @{" Destroy " Link Destroy} @{" DestroyAllTimers " Link DestroyAllTimers} @{" MakeTimer " Link MakeTimer} @endnode @node MakeTimer "MakeTimer function" Function prototype: Timer *MakeTimer(short flags, int (*CallFn) (Timer *, long)); Description: Create a new timer control. Parameters: flags: Two flags are available: TM_SECOND and TM_MINUTE. Only one of these should be specified. If you specify TM_SECOND, your timer function will be called once a second. If you specify TM_MINUTE, your timer function will be called once a minute. CallFn: A pointer to a function to call once a second or once a minute while the timer is running. At any time when the timer is stopped or paused, the function won't be called. The function should have the following prototype: int MyTimerFunction(Timer *WhichTimer, long TimeInSeconds) Your function will be passed a pointer to the timer that triggered it (you can have more than one timer calling the same function if you like) and the time (in seconds) since the timer was started (excluding any time during which the timer was paused). Your function should return either @{" GUI_END " Link GuiContinueEnd} or @{" GUI_CONTINUE " Link GuiContinueEnd}. Returns: If successful, a pointer to the new timer control. NULL otherwise. Known bugs: None. See also: @{" AddTime " Link AddTime} @{" DestroyTimer " Link DestroyTimer} @{" PauseTimer " Link PauseTimer} @{" SetTime " Link SetTime} @{" StartTimer " Link StartTimer} @{" StopTimer " Link StopTimer} @{" UnpauseTimer " Link UnpauseTimer} @endnode @node PauseTimer "PauseTimer function" Function prototype: void PauseTimer(Timer *t); Description: Pauses the specified timer (assuming it is currently running). When a timer is paused, your timer function will not get called at regular intervals as it would while the timer is running. However, unlike stopping a timer with the @{" StopTimer " Link StopTimer} function, the number of seconds that the timer has been running is retained and when the timer is unpaused using the @{" UnpauseTimer " Link UnpauseTimer} function it will continue counting the seconds from where it left off. Parameters: t: A pointer to the timer to pause. Known bugs: None. See also: @{" AddTime " Link AddTime} @{" SetTime " Link SetTime} @{" StartTimer " Link StartTimer} @{" StopTimer " Link StopTimer} @{" UnpauseTimer " Link UnpauseTimer} @endnode @node SetTime "SetTime function" Function prototype: void SetTime(Timer *t, long secs); Description: This function is used to set the elapsed time (the time that a timer has been running). Parameters: t: The timer control whose elapsed time you wish to set. secs: The time (in seconds) to which to set the elapsed time. Known bugs: Currently, this function cannot be used to set the time to 0. See also: @{" AddTime " Link AddTime} @{" PauseTimer " Link PauseTimer} @{" SetTime " Link SetTime} @{" StartTimer " Link StartTimer} @{" StopTimer " Link StopTimer} @{" UnpauseTimer " Link UnpauseTimer} @endnode @node StartTimer "StartTimer function" Function prototype: void StartTimer(Timer *t); Description: Starts the specified timer. If the timer is paused and you want to restart it without resetting the elapsed time to zero then use @{" UnpauseTimer " Link UnpauseTimer} instead of this function. StartTimer always resets the elapsed time to zero. Parameters: t: The timer to start. Known bugs: None. See also: @{" PauseTimer " Link PauseTimer} @{" SetTime " Link SetTime} @{" StopTimer " Link StopTimer} @{" UnpauseTimer " Link UnpauseTimer} @endnode @node StopTimer "StopTimer function" Function prototype: void StopTimer(Timer *t); Description: Stops the specified timer (assuming that it is running). If you wish to stop a timer and restart it later with the elapsed time preserved then you should use @{" PauseTimer " Link PauseTimer} instead of this function to stop the timer. When a timer is stopped or paused, the timer function isn't called. Parameters: t: The timer to stop. Known bugs: None. See also: @{" PauseTimer " Link PauseTimer} @{" StartTimer " Link StartTimer} @endnode @node UnpauseTimer "UnpauseTimer function" Function prototype: void UnpauseTimer(Timer *t); Description: Restart a paused timer, preserving the elapsed time as it was when the timer was paused. Parameters: t: The paused timer which you wish to "unpause". Known bugs: None. See also: @{" PauseTimer " Link PauseTimer} @{" StartTimer " Link StartTimer} @{" StopTimer " Link StopTimer} @endnode @node Screens "FoxGui Screen functions" All Amiga programs run on what is called a "screen". Initially a screen may have nothing on it other than a title bar across the top. Generally speaking, an application will open all of it's windows on one screen but this is not compulsory. An application may, if appropriate, open more than one screen or may choose not to open one at all but run on a public screen such as the workbench screen. If you wish to have control over the resolution of your applications display and the number of available colours then the simplest way is to open your own screen because that is where these attributes are defined. FoxGui screens are standard Intuition (Amiga) screens. This means that the user can control FoxGui screens in the same way as any other applications screens. Left Amiga-m can be used to flick between screens and left Amiga-n can be used to bring the workbench screen to the front. The following screen functions are currently available :- @{" CloseAllGuiScreens " Link CloseAllGuiScreens} @{" CloseGuiScreen " Link CloseGuiScreen} @{" OpenGuiScreen " Link OpenGuiScreen} @endnode @node OpenGuiScreen "OpenGuiScreen function" Function prototype: GuiScreen *OpenGuiScreen(int Depth, int DPen, int BPen, struct TextAttr *Font, char *Title, int (*LastWinFn)(GuiScreen *), int flags, ...); Description: Open a new screen with the attributes specified. Parameters: Depth: The number of planes for the screen. This determines the number of colours that can be shown on the screen (i.e. 1 plane gives 2 colours, 2 planes give four colours, 3 planes give 8 colours etc). DPen: The detail pen colour for the screen. BPen: The block pen colour for the screen. Font: A pointer to an initialised TextAttr structure which becomes the default font for the screen and for all windows on the screen. If font is NULL then topaz 8 is used. Title: A pointer to a null terminated character string to appear in the screens title bar. The Gui doesn't make a copy of this string, it uses the pointer supplied so you should make sure that this pointer remains valid while the screen is open. LastWinFn: For public screens, this can point to a function which you want to be triggered when the last visiting window (i.e. window opened by an application other than the current one) on your public screen is closed. If you wish, you can use the same function for more than one screen if your application has more than one. You can differentiate between the screens by using the GuiScreen pointer which is automatically passed to the function. The function should return either @{" GUI_END " Link GuiContinueEnd} or @{" GUI_CONTINUE " Link GuiContinueEnd}. If for example you wanted your application to finish as soon as the user closed the last window on the screen, you could do something like this: int MyLastWinFunction(GuiScreen *scr) { /* All visiting windows are now closed. Check to see whether any of my own windows are open. */ BOOL AllMyWindowsAreClosed = AllClosed(); if (AllMyWindowsAreClosed) return GUI_END; else return GUI_CONTINUE; } If you do not want a function triggered then pass NULL for LastWinFn. If PubName is NULL or "" or if the application is running on an OS version prior to V36 then LastWinFn is ignored. flags: The flags for screens fall into two categories - those that require extra data (supplied as extra parameters at the end of the OpenGuiScreen function) and those that don't. The flags that don't require any extra parameters are GS_AUTOSCROLL and GS_INTERLACE. GS_AUTOSCROLL specifies that if the screen width and height are greater than the display width and height then the screen will automatically scroll to reveal the rest of the screen whenever the mousepointer is brought close to the edge of the display. At the moment, OpenGuiScreen always opens the screen so that it fits the display so this flag is not very useful at the moment. The GS_INTERLACE flag specifies that the screen should be interlaced - this gives the screen twice as many rows (i.e. doubles the screen's vertical resolution) but can cause the display to be very flickery - especially on a TV screen. GS_INTERLACE will be ignored if the GS_DISPLAY_ID flag is used to describe the screenmode. The other screen flags (GS_PUBLIC, GS_DISPLAY_ID, GS_OVERSCAN and GS_PENS) all require extra parameters to be passed to OpenGuiScreen. It doesn't make any difference in which order the flags are specified (i.e. GS_PUBLIC | GS_PENS is exactly the same as GS_PENS | GS_PUBLIC) but if more than one of these flags is specified, it is essential that the extra parameters are passed in the right order. The correct order for the extra parameters is the order in which they are listed below. You should only pass a particular extra parameter if you have specified the appropriate flag. Specifying parameters whose flags have not been specified is likely to cause the function to fail, as is failing to specify extra parameters whose flags have been specified. Note that the names given for the extra parameters below are purely for reference within this text - they do not appear in the function prototype. The extra parameters:- char *PubName: A pointer to a NULL terminated character string to use as the screen's public name. You should only pass this parameter if the GS_PUBLIC flag has been specified. If PubName is NULL or "" or the GS_PUBLIC flag is not specified or the application is running under an OS version prior to V36 then the screen will be private (Public screens weren't available before V36), otherwise an attempt will be made to make the new screen public with the specified name. Specifying a PubName on an OS version prior to V36 will not cause the function to fail, the PubName will simply be ignored. ULONG DisplayID: An Intuition Display ID describing the screen mode for the new screen. This parameter should only be passed if the GS_DISPLAY_ID flag was specified and will be ignored if the application is run on an Amiga which does not support the ECS or AGA style display database. You should make sure that the DisplayID is valid by looking it up in the display database first. int OverScan: The overscan style to use for the new screen. This should have one of the values OSCAN_TEXT, OSCAN_STANDARD, OSCAN_MAX or OSCAN_VIDEO and should only be specified if the GS_OVERSCAN flag was specified. These values are defined by Intuition and you should see the Rom Kernel Reference Manuals for more information. UWORD *PenArray: A pointer to a Pen array for the new screen. This is an array of pen colours terminated by the value ~0. You should only pass this parameter if the GS_PENS flag was specified. If the GS_PENS flag is not specified then, if the application is used on an Amiga that does not support the three-d look, the Detail pen and Block pen specified in the DPen and BPen parameters will be used or, if the application is run on an Amiga which does support the three-d look then an attempt will be made to use a copy of the Workbench pens. If that attempt fails, then the default pen set will be used. Returns: If successful, a pointer to a valid GuiScreen structure is returned. If not then NULL is returned. Known bugs: None. See also: @{" CloseGuiScreen " Link CloseGuiScreen} @{" CloseAllGuiScreens " Link CloseAllGuiScreens} @{" ScreenColoursFromILBM " Link ScreenColoursFromILBM} @endnode @node CloseGuiScreen "CloseGuiScreen function" Function prototype: BOOL CloseGuiScreen(GuiScreen *scr); Description: Close the specified Gui screen. If the screen contains any open windows owned by the current application, they will be closed and the resources free'd. If the screen is public and contains any open windows owned by other applications then CloseGuiScreen() will fail. In this case, windows on the screen which are owned by the current application will still be closed. When running on an Amiga with a version of the OS prior to V36, CloseGuiScreen() will always succeed (Public screens were not implemented until V36). Parameters: scr: A pointer to an open GuiScreen. Returns: TRUE indicates success, FALSE indicates failure. Known bugs: None. See also: @{" OpenGuiScreen " Link OpenGuiScreen} @{" CloseAllGuiScreens " Link CloseAllGuiScreens} @endnode @node CloseAllGuiScreens "CloseAllGuiScreens function" Function prototype: void CloseAllGuiScreens(void); Description: Attempt to close all Gui screens open within this application. This is done by calling CloseGuiScreen() for each screen that belongs to this application. Since it is possible for CloseGuiScreen() to fail, it is not safe to assume that all of the screens will be closed after a call to CloseAllGuiScreens(). See CloseGuiScreen() for further details. Known bugs: None. See also: @{" CloseGuiScreen " Link CloseGuiScreen} @{" OpenGuiScreen " Link OpenGuiScreen} @endnode @node Windows "FoxGui Window functions" FoxGui windows are standard Intuition windows made easy. I'm not going to launch into a conceptual overview of what windows are and what you can do with them because if you're about to write an Amiga application then you're bound to know already and if you don't then you should probably read something else first. You can open one with a simple call to @{" OpenGuiWindow " Link OpenGuiWindow} and there are plenty of other windows functions below to make your programming life very simple. The following window functions are currently available :- @{" CloseAllWindows " Link CloseAllWindows} @{" CloseGuiWindow " Link CloseGuiWindow} @{" CloseScrWindows " Link CloseScrWindows} @{" OpenGuiWindow " Link OpenGuiWindow} @{" SetFName " Link SetFName} @{" SetPath " Link SetPath} @{" ShowFileRequester " Link ShowFileRequester} @{" SleepPointer " Link SleepPointer} @{" UpdateFList " Link UpdateFList} @{" WakePointer " Link WakePointer} The following window operations are defined as macros :- @{" WinBlankToEOL " Link WinBlankToEOL} @{" WinClear " Link WinClear} @{" WinHideCursor " Link WinHideCursor} @{" WinHome " Link WinHome} @{" WinPrint " Link WinPrint} @{" WinPrintCol " Link WinPrintCol} @{" WinPrintHi " Link WinPrintHi} @{" WinPrintTab " Link WinPrintTab} @{" WinShowCursor " Link WinShowCursor} @{" WinTab " Link WinTab} @{" WinWrapOff " Link WinWrapOff} @{" WinWrapOn " Link WinWrapOn} @endnode @node CloseAllWindows "CloseAllWindows function" Function prototype: void CloseAllWindows(void); Description: Close all open FoxGui windows in the current application, freeing all associated resources. Note that this will also destroy most FoxGui controls created in that window and free their resources (see the known bugs section). Known bugs: None. See also: @{" CloseGuiWindow " Link CloseGuiWindow} @{" CloseScrWindows " Link CloseScrWindows} @{" OpenGuiWindow " Link OpenGuiWindow} @{" SleepPointer " Link SleepPointer} @endnode @node CloseGuiWindow "CloseGuiWindow function" Function prototype: void CloseGuiWindow(GuiWindow *w); Description: Close the specified FoxGui window and all controls it contains, freeing all associated resources. Parameters: w: A pointer to an open FoxGui window as returned by @{" OpenGuiWindow " Link OpenGuiWindow}. Known bugs: None. See also: @{" CloseAllWindows " Link CloseAllWindows} @{" CloseScrWindows " Link CloseScrWindows} @{" OpenGuiWindow " Link OpenGuiWindow} @{" SleepPointer " Link SleepPointer} @endnode @node CloseScrWindows "CloseScrWindows function" Function prototype: void CloseScrWindows(GuiScreen *sc); Description: Close all FoxGui windows currently open on the specified FoxGui screen. Parameters: sc: A pointer to an open FoxGui screen as returned by the function @{" OpenGuiScreen " Link OpenGuiScreen}. Known bugs: None. See also: @{" CloseAllWindows " Link CloseAllWindows} @{" CloseGuiWindow " Link CloseGuiWindow} @{" OpenGuiWindow " Link OpenGuiWindow} @{" SleepPointer " Link SleepPointer} @endnode @node OpenGuiWindow "OpenGuiWindow function" Function prototype: GuiWindow *OpenGuiWindow(void *Scr, int Left, int Top, int Width, int Height, int minwidth, int minheight, int Dpen, int Bpen, int HiCol, char *Title, int flags, int (*CloseFn)(GuiWindow *), ...); Description: Open a new FoxGui window on the specified screen. Parameters: Scr: A pointer to an open FoxGui screen in which the window is to be opened or a text string containing the name of a public screen on which to open the window. If Scr is the name of a public screen and the application is run on an Amiga which does not support public screens or if the public screen does not exist the function will return NULL. Left: The coordinate of the left edge of the window relative to the left edge of the screen. Top: The coordinate of the top edge of the window relative to the top edge of the screen. Note that this is from the very top of the screen so a y coordinate of 0 will cause the window to at least partly obscure the screens title bar if it has one. Width: The width of the window in pixels. Height: The height of the window in pixels. minwidth: If the window has a size gadget (see the flags parameter) then this specifies the minimum width (in pixels) that the window can be sized to. minheight: If the window has a size gadget (see the flags parameter) then this specifies the minimum height (in pixels) that the window can be sized to. Dpen: The detail pen colour for the window. Bpen: The block pen for the window. The detail and block pen colours are passed directly to the intuition OpenWindow() function. When your application is run on OS2.0 or higher these parameters are largely ignored because intuition uses the screen's pen colours to create the 3D look for the window border. On earlier OS releases, these two parameters are used to determine the window colours. hicol: The hilight colour for the window. This does not directly affect the window colours but is used by other functions and macros such as @{" WinPrintHi " Link WinPrintHi} when drawing or printing text in the window. Title: A pointer to a NULL terminated text string to appear in the window's title bar. If you set this to NULL or "" then the window will have no title. Setting this to "" will force the window to have a title bar whereas NULL will allow the window to have no title bar at all (specifying some of the gadget flags such as GW_DRAG and GW_CLOSE will also force the window to have a title bar). If the Title is non-NULL then it is your responsibility to ensure that the text string remains valid - OpenGuiWindow does not make it's own copy of the string. flags: The following flags are currently available for Gui windows :- GW_CONSOLE, GW_DRAG, GW_BORDERLESS, GW_DEPTH, GW_CLOSE, GW_SIZE and GW_DROP. You can select more than one of these by ORing them together e.g. GW_DRAG | GW_DEPTH. GW_CONSOLE causes a console to be opened in the window. This allows you to easily write text into the window using the following console macros :- @{" WinBlankToEOL " Link WinBlankToEOL} @{" WinPrint " Link WinPrint} @{" WinShowCursor " Link WinShowCursor} @{" WinClear " Link WinClear} @{" WinPrintCol " Link WinPrintCol} @{" WinTab " Link WinTab} @{" WinHideCursor " Link WinHideCursor} @{" WinPrintHi " Link WinPrintHi} @{" WinWrapOff " Link WinWrapOff} @{" WinHome " Link WinHome} @{" WinPrintTab " Link WinPrintTab} @{" WinWrapOn " Link WinWrapOn} Note that Intuition places a limit on the number of consoles that can be open at a time which is currently 4. If you specify the GW_CONSOLE flag and the application can't open another console then OpenGuiWindow will fail and return NULL. GW_DRAG causes the window to be dragable (i.e. you can drag the window around the screen by pressing the left mouse button when the pointer is over the window's title bar and then keeping the button pressed down while you drag the mouse around the screen). GW_BORDERLESS causes the window to have no border. If any of the gadget flags are specified (such as GW_CLOSE) or the window has a title then the title bar will still be drawn but the border around it and around the other edges of the window will not be shown. GW_DEPTH will create a depth-gadget at the right hand end of the window's title bar. Clicking this when the window is partly obscured by other windows will bring the window to the front. If the window is already at the front then clicking the depth gadget will send the window to the back. On older versions of the Amiga OS, two gadgets are created - one for each of these functions. GW_SIZE causes the window to have a size gadget at the bottom of the right hand border. This allows the user to size the window. The minimum size the window can have is specified in the minwidth and minheight parameters. If controls within the window are created with the @{" S_AUTO_SIZE " Link S_AUTO_SIZE} flag set then they will automatically get moved and resized when the window is resized. For best results, open your window as small as possible so that the controls all fit in and are nicely spaced and set the minwidth and minheight parameters equal to the width and height parameters respectively. Making the window bigger will make the controls proportionately bigger too. GW_CLOSE will create a close gadget in the left hand end of the window's title bar. You can control the operation of the close gadget by supplying your own close gadget function (see the CloseFn parameter) or, if you don't supply a close gadget function, FoxGui will just close the window for you when the close gadget is clicked. GW_DROP specifies that the window is allowed to have items "dropped" into it when writing an application which has Drag and Drop functionality. If the GW_DROP flag is specified then an extra parameter must be specified immediately after the CloseFn parameter. The extra parameter is described below under the heading "Extra Parameter for the GW_DROP flag". CloseFn: A pointer to a user defined function to call when the window's close gadget is clicked by the user. The window will only have a close gadget if the GW_CLOSE flag was specified otherwise this parameter will be ignored. If this parameter is NULL and the GW_CLOSE flag was specified then FoxGui will close the window when the close gadget is clicked. If you wish to supply your own close gadget function then it should have the following prototype :- int CloseGadFn(GuiWindow *gw); As you can see, the function will be passed a pointer to the window whose close gadget was clicked, thus allowing you to use one function as the close gadget function for more than one window. Your function should return either @{" GUI_CONTINUE " Link GuiContinueEnd} or @{" GUI_END " Link GuiContinueEnd}. Either way, you are responsible for closing the window yourself - FoxGui doesn't do it for you. This is so that you can allow the user the option of cancelling the action if you wish. Extra parameter for the GW_DROP flag: If the flag GW_DROP is specified then a pointer to a function to handle objects dropped in the window must be passed to OpenGuiWindow immediately after the CloseFn parameter. The function should have the following prototype: int MyDropFunction(GuiWindow *WhichWindow, int x, int y, void *DropData); The function will be called whenever an object is dropped in the window. The function will be passed a pointer to the window that the data was dropped in (this allows you to use the same function to handle objects dropped in many windows if you so desire). It will also be passed the coordinates within the window of the exact point at which the object was dropped and a pointer to the data that was dropped in the window (the pointer provided will be the one that was initialised by the initiating "drag" function if any). Unlike the event function for a Frame, the drop function for a window receives a pointer to the dragged data (rather than a pointer to a pointer to the dragged data). This is because you cannot drag data out of a window - only into it and so you will never need to modify the data pointer from within a window's drop function. For further information on drag and drop see the @{" MakeFrame " Link MakeFrame} function. Returns: If successful, a pointer to the new FoxGui window is returned. Otherwise NULL is returned. Known bugs: None. See also: @{" Drag/Drop functionality " Link DragDropFunc} @{" CloseAllWindows " Link CloseAllWindows} @{" CloseGuiWindow " Link CloseGuiWindow} @{" CloseScrWindows " Link CloseScrWindows} @{" ShowFileRequester " Link ShowFileRequester} @{" SleepPointer " Link SleepPointer} @{" WakePointer " Link WakePointer} @endnode @node SetFName "SetFName function" Function prototype: void SetFName(char *fname); Description: Set the file name in an open, non ASL file requester created by calling the function @{" ShowFileRequester " Link ShowFileRequester}. You would typically use this to reset the file name if the user had attempted to open a file that didn't exist. Note that if your application is running on an Amiga with ASL library version 37 or greater then ShowFileRequester will open an ASL file requester (the standard Amiga file requester). In this case, this function will do nothing. Parameters: fname: A pointer to a NULL terminated text string containing the file name to put in the file requester. It is not necessary to maintain the string after calling the function because FoxGui will make it's own copy of the string. Known bugs: None. See also: @{" SetPath " Link SetPath} @{" ShowFileRequester " Link ShowFileRequester} @{" UpdateFList " Link UpdateFList} @endnode @node SetPath "SetPath function" Function prototype: void SetPath(char *path); Description: Set the file path in an open, non ASL file requester created by calling the function @{" ShowFileRequester " Link ShowFileRequester}. You would typically use this to reset the file path if the user had attempted to open a file that didn't exist. Note that if your application is running on an Amiga with ASL library version 37 or greater then ShowFileRequester will open an ASL file requester (the standard Amiga file requester). In this case, this function will do nothing. Parameters: path: A pointer to a NULL terminated text string containing the file path to put in the file requester. It is not necessary to maintain the string after calling the function because FoxGui will make it's own copy of the string. Known bugs: None. See also: @{" SetFName " Link SetFName} @{" ShowFileRequester " Link ShowFileRequester} @{" UpdateFList " Link UpdateFList} @endnode @node ShowFileRequester "ShowFileRequester function" Function prototype: BOOL ShowFileRequester(GuiWindow *Wnd, char *path, char *pattern, char *title, BOOL Save, int (*callfn) (char*, char*), int Col_GW1, int Col_GW2, int Col_GW3, int Col_OB1, int Col_OB2, int Col_EB1, int Col_EB2, int Col_EB3, int Col_B1); Description: Show a file requester. On Amigas with ASL library version 37 or above, this will open a standard ASL file requester, allowing the user to select the filename and path of a file to perform some specific action on (usually loading or saving the file). On Amigas without the ASL library a functionally equivalent file requester is opened which allows a file name and path to be selected in exactly the same way. Many of the parameters to this function are not required on Amigas with the ASL library because they are only used for the FoxGui implementation of the file requester but it is recommended that you give sensible values anyway so that the file requester will appear correctly if your application is run on older Amigas. Parameters: Wnd: A file requester must be "attached" to a window. Wnd should be a pointer to an open FoxGui window to which the file requester will be attached. Any open FoxGui window will do - the window will not be changed in any way. The only criterion to use when deciding which window to pass is which screen you want the file requester to appear in. The file requester will always appear on the same screen as the window that you attach it to. path: The initial file path for the file requester. pattern: This allows you to filter the files that appear in the file list. Directories will always be shown. If you want all files to be shown then set the pattern to "" (never set this to NULL). If the pattern is not blank then the last characters of the filename must match the pattern e.g. if the pattern is set to "fox" then only file names ending "fox" will be shown. You would usually use this to show files of a certain type, e.g. to only show AmigaGuide files you might set this to ".guide". Note that the pattern is not case sensitive so ".guide" would also match ".GUIDE" or ".Guide" etc. title: The title to appear in the top border of the file requester. Save: If TRUE then the left-most button on the file requester will have the caption "Save" otherwise it will have the caption "Load". The colours of the file list are also inverted for Save file requesters. callfn: A pointer to a user-defined function to call when the Save or Load button is pressed. Your function should have the following prototype:- int MyFileFn(char *FName, char *FPath); Your function will be passed the filename and file path of the file selected by the user in the parameters FName and FPath respectively. Note that there is no guarantee that the path or the file exists because the user can type directly into the filename and path edit boxes in the file requester as well as select files from the file list. You should not modify the strings passed to this function as they are required by FoxGui - make your own copy and modify that if necessary. Your function should return either GUI_MODAL_END or @{" GUI_CONTINUE " Link GuiContinueEnd}. If GUI_MODAL_END is returned, the file requester will go away immediately. If GUI_CONTINUE is returned, the file requester will remain present. You would typically return GUI_CONTINUE if your function failed for some reason and GUI_MODAL_END otherwise. The remaining parameters specify the colours used when creating the file requester. These are ignored if the ASL file requester is used (see above). Col_GW1, Col_GW2, Col_GW3: The colours for the file requester. These are the same as the Dpen, Bpen and hicol parameters to the @{" OpenGuiWindow " Link OpenGuiWindow} function. Col_OB1, Col_OB2: The colours for the fixed text in the file requester. These are the same as the Bcol and Tcol parameters to the @{" MakeOutputBox " Link MakeOutputBox} function. Col_EB1, Col_EB2, Col_EB3: The colours for the Filename and Path edit boxes. These are the same as the BorderCol, Bcol and Tcol parameters to the @{" MakeEditBox " Link MakeEditBox} function. Col_B1: The text colour for the buttons. This is the same as the tcol parameter to the @{" MakeButton " Link MakeButton} function. Returns: TRUE for success, FALSE for failure. Known bugs: None. Other notes: I originally implemented this file requester without the ASL library. It was designed to remain shown until you press the "Done" button. The idea was that you selected a file to load (or save), pressed the "Load" (or "Save") button and while your user-defined function did the necessary loading or saving, the file requester would remain shown but temporarily disabled. The ASL file requester behaves slightly differently - it goes away as soon as the Load or Save button is pressed. I didn't want this to happen because occasionally, when loading, the user may mistype a file name or saving may fail due to a floppy being write protected or the disk being full and I thought the file requester should still be there so that they could try again and should only disappear when the user clicked on the Done button. For this reason, I have implemented this in such a way that if the ASL file requester is used, it disappears during loading or saving (I have no control over that) but it reappears once loading/saving is complete if (and only if) your load/save function returns GUI_CONTINUE. If your load/save function returns GUI_MODAL_END then the file requester will go away. See also: @{" SetFName " Link SetFName} @{" SetPath " Link SetPath} @{" UpdateFList " Link UpdateFList} @endnode @node SleepPointer "SleepPointer function" Function prototype: BOOL SleepPointer(GuiWindow *win); Description: Puts the specified window to sleep (the mouse pointer becomes the stop-clock whenever the specified window is active. All controls in the window become inactive). The window can be woken again with the function @{" WakePointer " Link WakePointer}. Parameters: win: A pointer to an open FoxGui window. Returns: TRUE for success, FALSE for failure. Known bugs: Due to a bug in earlier versions of the Amiga OS, it is impossible to detect (on early Amigas) whether the method that this function uses to disable the window has actually succeeded so on earlier Amigas this function always returns TRUE. On later Amigas the return value is completely reliable. In practice I have never known the window disabling to fail so this is unlikely to cause problems. See also: @{" WakePointer " Link WakePointer} @endnode @node UpdateFList "UpdateFList function" Function prototype: void UpdateFList(void); Description: Forces an open file requester to update it's file list. This function does nothing on Amigas which use the ASL file requester (see the @{" ShowFileRequester " Link ShowFileRequester} function). If no file requester is open, this function does nothing. Known bugs: None. See also: @{" SetFName " Link SetFName} @{" SetPath " Link SetPath} @{" ShowFileRequester " Link ShowFileRequester} @endnode @node WakePointer "WakePointer function" Function prototype: void WakePointer(GuiWindow *win); Description: Wake up a window previously put to sleep by the @{" SleepPointer " Link SleepPointer} function. If the window is not asleep then this function does nothing. Parameters: win: A pointer to the FoxGui window to wake up. Known bugs: None. See also: @{" SleepPointer " Link SleepPointer} @endnode @node WinBlankToEOL "WinBlankToEOL macro" Macro prototype: void WinBlankToEOL(GuiWindow *w) Macro definition: #define WinBlankToEOL(w) ConBlankToEOL((w)->Con) Description: Blank from the current cursor position to the end of the current line in the console attached to the specified window. The cursor can be moved with the @{" WinTab " Link WinTab} macro. Parameters: w: A pointer to an open FoxGui window which has a console attached. See also: @{" Warnings on the use of macros " Link MacroWarnings} @{" OpenGuiWindow " Link OpenGuiWindow} @{" WinClear " Link WinClear} @{" WinHideCursor " Link WinHideCursor} @{" WinHome " Link WinHome} @{" WinPrint " Link WinPrint} @{" WinPrintCol " Link WinPrintCol} @{" WinPrintHi " Link WinPrintHi} @{" WinPrintTab " Link WinPrintTab} @{" WinShowCursor " Link WinShowCursor} @{" WinTab " Link WinTab} @{" WinWrapOff " Link WinWrapOff} @{" WinWrapOn " Link WinWrapOn} @endnode @node WinClear "WinClear macro" Macro prototype: void WinClear(GuiWindow *w) Macro definition: #define WinClear(w) ConClear((w)->Con) Description: Clear the console in the specified FoxGui window. Parameters: w: A pointer to an open FoxGui window which has a console attached. See also: @{" Warnings on the use of macros " Link MacroWarnings} @{" OpenGuiWindow " Link OpenGuiWindow} @{" WinBlankToEOL " Link WinBlankToEOL} @{" WinHideCursor " Link WinHideCursor} @{" WinHome " Link WinHome} @{" WinPrint " Link WinPrint} @{" WinPrintCol " Link WinPrintCol} @{" WinPrintHi " Link WinPrintHi} @{" WinPrintTab " Link WinPrintTab} @{" WinShowCursor " Link WinShowCursor} @{" WinTab " Link WinTab} @{" WinWrapOff " Link WinWrapOff} @{" WinWrapOn " Link WinWrapOn} @endnode @node WinHideCursor "WinHideCursor macro" Macro prototype: void WinHideCursor(GuiWindow *w) Macro definition: #define WinHideCursor(w) ConHideCursor((w)->Con) Description: Hides the cursor in a FoxGui window which has a console attached. By default the cursor is visible and at the top left corner of the window. The cursor can be moved by the @{" WinTab " Link WinTab} macro and by macros which print text in the console such as @{" WinPrint " Link WinPrint}. After being hidden, the cursor can be shown again with the macro @{" WinShowCursor " Link WinShowCursor}. Parameters: w: A pointer to an open FoxGui window which has a console attached. See also: @{" Warnings on the use of macros " Link MacroWarnings} @{" OpenGuiWindow " Link OpenGuiWindow} @{" WinBlankToEOL " Link WinBlankToEOL} @{" WinClear " Link WinClear} @{" WinHome " Link WinHome} @{" WinPrint " Link WinPrint} @{" WinPrintCol " Link WinPrintCol} @{" WinPrintHi " Link WinPrintHi} @{" WinPrintTab " Link WinPrintTab} @{" WinShowCursor " Link WinShowCursor} @{" WinTab " Link WinTab} @{" WinWrapOff " Link WinWrapOff} @{" WinWrapOn " Link WinWrapOn} @endnode @node WinHome "WinHome macro" Macro prototype: void WinHome(GuiWindow *w) Macro definition: #define WinHome(w) ConHome((w)->Con) Description: Moves the cursor to the top left of the specified FoxGui window which has a cursor attached. Calling WinHome(MyWindow) is entirely equivalent to calling WinTab(MyWindow, 1, 1). Parameters: w: A pointer to an open FoxGui window which has a console attached. See also: @{" Warnings on the use of macros " Link MacroWarnings} @{" OpenGuiWindow " Link OpenGuiWindow} @{" WinBlankToEOL " Link WinBlankToEOL} @{" WinClear " Link WinClear} @{" WinHideCursor " Link WinHideCursor} @{" WinPrint " Link WinPrint} @{" WinPrintCol " Link WinPrintCol} @{" WinPrintHi " Link WinPrintHi} @{" WinPrintTab " Link WinPrintTab} @{" WinShowCursor " Link WinShowCursor} @{" WinTab " Link WinTab} @{" WinWrapOff " Link WinWrapOff} @{" WinWrapOn " Link WinWrapOn} @endnode @node WinPrint "WinPrint macro" Macro prototype: void WinPrint(GuiWindow *w, char *str) Macro definition: #define WinPrint(w,str) ConPrint((w)->Con,str) Description: Prints the specified text string at the current cursor position in the console attached to the specified open FoxGui window. If the text is too long to fit between the current cursor position and the end of the current line in the console then the text will either be truncated or the text will continue at the beginning of the next line of the console. Whether or not the text is truncated depends on whether text wrapping is turned on in the console. Text wrapping can be turned on and off with the macros @{" WinWrapOn " Link WinWrapOn} and @{" WinWrapOff " Link WinWrapOff} respectively. If the text reaches the bottom right hand corner of the window and text wrapping is turned on then the console will scroll up a line to allow room for the next line of text. This will remove the top line of text from the window. After printing the text, the cursor will be positioned immediately after the last character that was printed unless the right hand edge of the console has been reached with text wrapping turned off in which case the cursor will be on the last character printed. Parameters: w: A pointer to an open FoxGui window which has a console attached. str: The text that you want to be printed at the current cursor position in the specified windows console. See also: @{" Warnings on the use of macros " Link MacroWarnings} @{" OpenGuiWindow " Link OpenGuiWindow} @{" WinBlankToEOL " Link WinBlankToEOL} @{" WinClear " Link WinClear} @{" WinHideCursor " Link WinHideCursor} @{" WinHome " Link WinHome} @{" WinPrintCol " Link WinPrintCol} @{" WinPrintHi " Link WinPrintHi} @{" WinPrintTab " Link WinPrintTab} @{" WinShowCursor " Link WinShowCursor} @{" WinTab " Link WinTab} @{" WinWrapOff " Link WinWrapOff} @{" WinWrapOn " Link WinWrapOn} @endnode @node WinPrintCol "WinPrintCol macro" Macro prototype: void WinPrintCol(GuiWindow *w, char *str, int col) Macro definition: #define WinPrintCol(w,str,col) ConPrintHi((w)->Con,str,col) Description: This function prints the text string specified into the console of the specified open FoxGui window (the window must have a console attached at the time it is opened) in the specified colour. The way the text is printed will depend on whether text wrapping is currently turned on or off in the console. See @{" WinPrint " Link WinPrint} for a full explanation. Parameters: w: A pointer to an open FoxGui window which has a console attached. str: The text that you want to be printed at the current cursor position in the specified windows console. col: The colour in which the text should be printed. This should be an integer whose maximum value will be dependant on the number of bitplanes used by the screen. For example, if the screen is opened with one bitplane then col should be between 0 and 1. If the screen has two bitplanes then col should be between 0 and 3. In general, col should be between 0 and 2^n - 1 where n is the number of bitplanes. See also: @{" Warnings on the use of macros " Link MacroWarnings} @{" OpenGuiWindow " Link OpenGuiWindow} @{" WinBlankToEOL " Link WinBlankToEOL} @{" WinClear " Link WinClear} @{" WinHideCursor " Link WinHideCursor} @{" WinHome " Link WinHome} @{" WinPrint " Link WinPrint} @{" WinPrintHi " Link WinPrintHi} @{" WinPrintTab " Link WinPrintTab} @{" WinShowCursor " Link WinShowCursor} @{" WinTab " Link WinTab} @{" WinWrapOff " Link WinWrapOff} @{" WinWrapOn " Link WinWrapOn} @endnode @node WinPrintHi "WinPrintHi macro" Macro prototype: void WinPrintHi(GuiWindow *w, char *str) Macro definition: #define WinPrintHi(w,str) ConPrintHi((w)->Con,str,(w)->HighCol) Description: This function prints the text string specified into the console of the specified open FoxGui window (the window must have a console attached at the time it is opened) in the windows hilight colour. The hilight colour is passed as a parameter to @{" OpenGuiWindow " Link OpenGuiWindow} when the window is first opened. The way the text is printed will depend on whether text wrapping is currently turned on or off in the console. See @{" WinPrint " Link WinPrint} for a full explanation. Parameters: w: A pointer to an open FoxGui window which has a console attached. str: The text that you want to be printed at the current cursor position in the specified windows console. See also: @{" Warnings on the use of macros " Link MacroWarnings} @{" OpenGuiWindow " Link OpenGuiWindow} @{" WinBlankToEOL " Link WinBlankToEOL} @{" WinClear " Link WinClear} @{" WinHideCursor " Link WinHideCursor} @{" WinHome " Link WinHome} @{" WinPrint " Link WinPrint} @{" WinPrintCol " Link WinPrintCol} @{" WinPrintTab " Link WinPrintTab} @{" WinShowCursor " Link WinShowCursor} @{" WinTab " Link WinTab} @{" WinWrapOff " Link WinWrapOff} @{" WinWrapOn " Link WinWrapOn} @endnode @node WinPrintTab "WinPrintTab macro" Macro prototype: void WinPrintTab(GuiWindow *w, int x, int y, char *str) Macro definition: #define WinPrintTab(w,x,y,str) ConPrintTab((w)->Con,x,y,str) Description: This function first moves the console cursor of the specified open FoxGui window to the coordinates given in x and y and then prints the specified text string at that position. Calling this macro is equivalent to calling the @{" WinTab " Link WinTab} macro followed by the @{" WinPrint " Link WinPrint} macro and you should read the sections on those two macros for further details. Parameters: w: A pointer to an open FoxGui window which has a console attached. x: The x coordinate to move the cursor to before printing the text. y: The y coordinate to move the cursor to before printing the text. str: The text that you want to be printed. See also: @{" Warnings on the use of macros " Link MacroWarnings} @{" OpenGuiWindow " Link OpenGuiWindow} @{" WinBlankToEOL " Link WinBlankToEOL} @{" WinClear " Link WinClear} @{" WinHideCursor " Link WinHideCursor} @{" WinHome " Link WinHome} @{" WinPrint " Link WinPrint} @{" WinPrintCol " Link WinPrintCol} @{" WinPrintHi " Link WinPrintHi} @{" WinShowCursor " Link WinShowCursor} @{" WinTab " Link WinTab} @{" WinWrapOff " Link WinWrapOff} @{" WinWrapOn " Link WinWrapOn} @endnode @node WinShowCursor "WinShowCursor macro" Macro prototype: void WinShowCursor(GuiWindow *w) Macro definition: #define WinShowCursor(w) ConShowCursor((w)->Con) Description: Shows the cursor in the specified window. The window must have a console attached. The cursor is shown by default so it is only necessary to call this function if you have previously hidden the cursor with the @{" WinHideCursor " Link WinHideCursor} macro and you now want to make it visible again. Parameters: w: A pointer to the open FoxGui window whose console cursor you wish to show. See also: @{" Warnings on the use of macros " Link MacroWarnings} @{" OpenGuiWindow " Link OpenGuiWindow} @{" WinBlankToEOL " Link WinBlankToEOL} @{" WinClear " Link WinClear} @{" WinHideCursor " Link WinHideCursor} @{" WinHome " Link WinHome} @{" WinPrint " Link WinPrint} @{" WinPrintCol " Link WinPrintCol} @{" WinPrintHi " Link WinPrintHi} @{" WinPrintTab " Link WinPrintTab} @{" WinTab " Link WinTab} @{" WinWrapOff " Link WinWrapOff} @{" WinWrapOn " Link WinWrapOn} @endnode @node WinTab "WinTab macro" Macro prototype: void WinTab(GuiWindow *w, int x, int y) Macro definition: #define WinTab(w,x,y) ConTab((w)->Con,x,y) Description: Move the specified windows console cursor to the coordinates specified. Console coordinates have the origin at (1,1). i.e. the top left of the console is at x=1, y=1. Specifying 0 for either coordinate will just set that coordinate to 1. Parameters: w: A pointer to an open FoxGui window which has a console attached. x: The x coordinate to move the cursor to. y: The y coordinate to move the cursor to. See also: @{" Warnings on the use of macros " Link MacroWarnings} @{" OpenGuiWindow " Link OpenGuiWindow} @{" WinBlankToEOL " Link WinBlankToEOL} @{" WinClear " Link WinClear} @{" WinHideCursor " Link WinHideCursor} @{" WinHome " Link WinHome} @{" WinPrint " Link WinPrint} @{" WinPrintCol " Link WinPrintCol} @{" WinPrintHi " Link WinPrintHi} @{" WinPrintTab " Link WinPrintTab} @{" WinShowCursor " Link WinShowCursor} @{" WinWrapOff " Link WinWrapOff} @{" WinWrapOn " Link WinWrapOn} @endnode @node WinWrapOff "WinWrapOff macro" Macro prototype: void WinWrapOff(GuiWindow *w) Macro definition: #define WinWrapOff(w) ConWrapOff((w)->Con) Description: Turn off text wrapping for the console in the specified FoxGui window. For a description of how text wrapping affects the way text is printed in a console, see the @{" WinPrint " Link WinPrint} macro. Parameters: w: A pointer to an open FoxGui window which has a console attached. See also: @{" Warnings on the use of macros " Link MacroWarnings} @{" OpenGuiWindow " Link OpenGuiWindow} @{" WinBlankToEOL " Link WinBlankToEOL} @{" WinClear " Link WinClear} @{" WinHideCursor " Link WinHideCursor} @{" WinHome " Link WinHome} @{" WinPrint " Link WinPrint} @{" WinPrintCol " Link WinPrintCol} @{" WinPrintHi " Link WinPrintHi} @{" WinPrintTab " Link WinPrintTab} @{" WinShowCursor " Link WinShowCursor} @{" WinTab " Link WinTab} @{" WinWrapOn " Link WinWrapOn} @endnode @node WinWrapOn "WinWrapOn macro" Macro prototype: void WinWrapOn(GuiWindow *w) Macro definition: #define WinWrapOn(w) ConWrapOn((w)->Con) Description: Turn on text wrapping for the console in the specified FoxGui window. For a description of how text wrapping affects the way text is printed in a console, see the @{" WinPrint " Link WinPrint} macro. Parameters: w: A pointer to an open FoxGui window which has a console attached. See also: @{" Warnings on the use of macros " Link MacroWarnings} @{" OpenGuiWindow " Link OpenGuiWindow} @{" WinBlankToEOL " Link WinBlankToEOL} @{" WinClear " Link WinClear} @{" WinHideCursor " Link WinHideCursor} @{" WinHome " Link WinHome} @{" WinPrint " Link WinPrint} @{" WinPrintCol " Link WinPrintCol} @{" WinPrintHi " Link WinPrintHi} @{" WinPrintTab " Link WinPrintTab} @{" WinShowCursor " Link WinShowCursor} @{" WinTab " Link WinTab} @{" WinWrapOff " Link WinWrapOff} @endnode @node Menus "FoxGui Menu functions" Menus are attached to FoxGui windows and appear in the title bar of the screen containing the window when the right mouse button is pressed down (but then, being an Amiga user you already knew that). FoxGui allows a set of menus to be shared between multiple windows without having to create an identical set for each window (see @{" ShareMenus " Link ShareMenus} below). The functions below should be obvious by their names. The following menu functions are currently available :- @{" AddMenu " Link AddMenu} @{" AddMenuItem " Link AddMenuItem} @{" AddSubMenuItem " Link AddSubMenuItem} @{" ClearMenus " Link ClearMenus} @{" DisableMenu " Link DisableMenu} @{" DisableMenuItem " Link DisableMenuItem} @{" DisableWinMenus " Link DisableWinMenus} @{" EnableMenu " Link EnableMenu} @{" EnableMenuItem " Link EnableMenuItem} @{" EnableWinMenus " Link EnableWinMenus} @{" RemoveMenuItem " Link RemoveMenuItem} @{" SetWinMenuFn " Link SetWinMenuFn} @{" ShareMenus " Link ShareMenus} @endnode @node AddMenu "AddMenu function" Function prototype: struct Menu *AddMenu(GuiWindow *win, char *name, int leftedge, int enabled); Description: Add a new top-level menu to the specified Gui window. Note that each gui window can have no more than 31 top-level menus. More than one Gui window can share the same set of menus - see @{" ShareMenus " Link ShareMenus} Parameters: win: A pointer to an open Gui window to which a new top-line menu will be added. name: A pointer to a NULL-terminated text string which will appear in the gui window's menu bar. leftedge: The offset of the new menu from the left hand edge of the screen in pixels. enabled: If FALSE, the menu will initially be disabled. Otherwise enabled. Returns: If successful, a pointer to the new menu structure is returned. You will need to pass this to the function AddMenuItem when adding items to this top-line menu. If AddMenu fails, NULL is returned. Known bugs: None. See also: @{" AddMenuItem " Link AddMenuItem} @{" ClearMenus " Link ClearMenus} @{" DisableMenu " Link DisableMenu} @{" DisableWinMenus " Link DisableWinMenus} @{" EnableMenu " Link EnableMenu} @{" EnableWinMenus " Link EnableWinMenus} @{" SetWinMenuFn " Link SetWinMenuFn} @{" ShareMenus " Link ShareMenus} @endnode @node AddMenuItem "AddMenuItem function" Function prototype: struct MenuItem *AddMenuItem(GuiWindow *win, struct Menu *menu, char *name, char *selname, unsigned short flags, int key, int enabled, int checkit, int checked, int menutoggle); Description: Adds a new menu item to the specified top-level menu in the specified window. There are three types of menu items - those that perform some user-defined action (these are known as Action items and have no special imagery), those that toggle between two states (these are known as Checkmark items and have a tick to the left of the item text which is either shown or hidden depending on their state) and those which contain sub-menus (these have the » symbol to the right of the text to indicate that a submenu is present). Shortcut keys can be applied to the first two types of menu. Menus containing sub-menus are made in exactly the same way as action menus. The sub-menu is then added using calls to the function @{" AddSubMenuItem " Link AddSubMenuItem}. Note that each top-level menu can contain no more than 63 menu items Parameters: win: A pointer to the open Gui window that the menu item is to be added to. menu: A pointer to the top-level menu which this item is to appear in. name: A pointer to a NULL-terminated text string to appear in the drop down menu. selname: A pointer to an optional NULL-terminated text string to be displayed when the menu option is hilighted instead of the more usual hilighting method of inverting the pixels. Use NULL for normal hilighting. flags: Currently unused but reserved for future enhancements. To ensure compatibility with later versions, set this to zero. key: The shortcut key for the menu. For example, passing 'Q' would make right Amiga-Q the hotkey for the menu. Pressing right Amiga-Q would then have the same effect as selecting the menu. Pass 0 if no shortcut key is required. enabled: If FALSE, the menu item will initially be disabled. Otherwise enabled. checkit: If TRUE then this will be a Checkmark item. checked: Set this to TRUE if the item is a Checkmark item and you want it to be initially checked (i.e. you want the tick to appear). If this is an action item or if it is a checkmark item which you want to be initially unchecked then set this to FALSE. menutoggle: Set this to TRUE if the item is a Checkmark item and you wish to be able to toggle the state by repeated selection of the item. If this is FALSE and the item is a Checkmark item, the only way for the item to become un-checked is by mutual-exclusion which is not currently supported by FoxGui. Returns: If successful, a pointer to the new menu item is returned. In the event of failure, NULL is returned. Known bugs: None. See also: @{" AddMenu " Link AddMenu} @{" AddSubMenuItem " Link AddSubMenuItem} @{" ClearMenus " Link ClearMenus} @{" DisableMenuItem " Link DisableMenuItem} @{" EnableMenuItem " Link EnableMenuItem} @{" SetWinMenuFn " Link SetWinMenuFn} @{" ShareMenus " Link ShareMenus} @endnode @node AddSubMenuItem "AddSubMenuItem function" Function prototype: struct MenuItem *AddSubMenuItem(GuiWindow *win, struct MenuItem *menuitem, char *name, char *selname, unsigned short flags, int key, int enabled, int checkit, int checked, int menutoggle); Description: Adds a sub-menu item to the specified existing menu item in the specified window. Note that each menu item may have a maximum of 31 sub-menu items. Parameters: menuitem: A pointer to an item in an existing menu structure. This item will become the parent item for the sub-menu item created. If the parent item already has sub-menu items then the new one will be added to the end of the sub-menu, otherwise a new sub-menu will be created with this item being the first in the new sub-menu. AddSubMenuItem will fail if the menuitem specified to be the parent is itself a sub-menu item as sub-sub-menu items are not supported. All other parameters are identical to the parameters of the function @{" AddMenuItem " Link AddMenuItem}. Returns: If successful, a pointer to the new sub-menu item is returned. In the event of failure, NULL is returned. Known bugs: None. See also: @{" AddMenu " Link AddMenu} @{" AddMenuItem " Link AddMenuItem} @{" ClearMenus " Link ClearMenus} @{" DisableMenuItem " Link DisableMenuItem} @{" EnableMenuItem " Link EnableMenuItem} @{" SetWinMenuFn " Link SetWinMenuFn} @{" ShareMenus " Link ShareMenus} @endnode @node ClearMenus "ClearMenus function" Function prototype: void ClearMenus(GuiWindow *win); Description: Removes all top-level menus, menu items and sub-menu items from the specified Gui window. If the menus are shared with other Gui windows, the other windows remain unaffected. If the menus are not shared with other windows, all the resources used by the menus are released. You should always call ClearMenus before closing a Gui window which has menus. Parameters: win: The Gui window whose menus are to be cleared. Known bugs: None. @endnode @node DisableMenu "DisableMenu function" Function prototype: BOOL DisableMenu(GuiWindow *win, struct Menu *menu); Description: Disables the specified top-level menu in the specified window and all other windows which share the same menu strip. This prevents the menu from being dropped and hence prevents selection of any of the menu items within it. The menu text will appear ghosted. Parameters: win: A pointer to the window containing the menu to be disabled. menu: A pointer to the top-level menu to be disabled. Returns: TRUE for success, FALSE for failure. Known bugs: None. See also: @{" DisableMenuItem " Link DisableMenuItem} @{" DisableWinMenus " Link DisableWinMenus} @{" EnableMenu " Link EnableMenu} @{" EnableMenuItem " Link EnableMenuItem} @{" EnableWinMenus " Link EnableWinMenus} @endnode @node DisableMenuItem "DisableMenuItem function" Function prototype: BOOL DisableMenuItem(GuiWindow *win, struct MenuItem *item); Description: Disables the specified menu-item in the specified window and all other windows that share the same menu strip. The item text will appear ghosted and will become un-selectable. Parameters: win: A pointer to the Gui window containing the menu item. item: A pointer to the item to be disabled. Returns: TRUE for success, FALSE for failure. Known bugs: None. See also: @{" DisableMenu " Link DisableMenu} @{" DisableWinMenus " Link DisableWinMenus} @{" EnableMenu " Link EnableMenu} @{" EnableMenuItem " Link EnableMenuItem} @{" EnableWinMenus " Link EnableWinMenus} @endnode @node DisableWinMenus "DisableWinMenus function" Function prototype: BOOL DisableWinMenus(GuiWindow *win); Description: Disables all menus in the window specified and all other windows that share the same menu strip. Parameters: win: A pointer to the Gui window whose menus are to be disabled. Returns: TRUE for success, FALSE for failure. Known bugs: None. See also: @{" DisableMenu " Link DisableMenu} @{" DisableMenuItem " Link DisableMenuItem} @{" EnableMenu " Link EnableMenu} @{" EnableMenuItem " Link EnableMenuItem} @{" EnableWinMenus " Link EnableWinMenus} @endnode @node EnableMenu "EnableMenu function" Function prototype: BOOL EnableMenu(GuiWindow *win, struct Menu *menu); Description: Enables the specified top-level menu in the specified window and all other windows which share the same menu strip. Parameters: win: A pointer to the window containing the menu to be enabled. menu: A pointer to the top-level menu to be enabled. Returns: TRUE for success, FALSE for failure. Known bugs: None. See also: @{" DisableMenu " Link DisableMenu} @{" DisableMenuItem " Link DisableMenuItem} @{" DisableWinMenus " Link DisableWinMenus} @{" EnableMenuItem " Link EnableMenuItem} @{" EnableWinMenus " Link EnableWinMenus} @endnode @node EnableMenuItem "EnableMenuItem function" Function prototype: BOOL EnableMenuItem(GuiWindow *win, struct MenuItem *item); Description: Enables the specified menu-item in the specified window and all other windows that share the same menu strip. Parameters: win: A pointer to the Gui window containing the menu item. item: A pointer to the item to be enabled. Returns: TRUE for success, FALSE for failure. Known bugs: None. See also: @{" DisableMenu " Link DisableMenu} @{" DisableMenuItem " Link DisableMenuItem} @{" DisableWinMenus " Link DisableWinMenus} @{" EnableMenu " Link EnableMenu} @{" EnableWinMenus " Link EnableWinMenus} @endnode @node EnableWinMenus "EnableWinMenus function" Function prototype: BOOL EnableWinMenus(GuiWindow *win); Description: Enables all menus in the window specified and all other windows that share the same menu strip. Parameters: win: A pointer to the Gui window whose menus are to be enabled. Returns: TRUE for success, FALSE for failure. Known bugs: None. See also: @{" DisableMenu " Link DisableMenu} @{" DisableMenuItem " Link DisableMenuItem} @{" DisableWinMenus " Link DisableWinMenus} @{" EnableMenu " Link EnableMenu} @{" EnableMenuItem " Link EnableMenuItem} @endnode @node RemoveMenuItem "RemoveMenuItem function" Function prototype: BOOL RemoveMenuItem(GuiWindow *win, struct MenuItem *item); Description: Removes the specified menu item from it's parent menu in the specified window. If the menu strip for that window is shared with other windows then the item is removed from all of those windows. If the item has sub-menu items below it then that sub-menu will also be removed. Parameters: win: The window from which a menu item is to be removed. item: A pointer to the menu item which is to be removed. If the item is removed successfully then this pointer will no-longer point to a meaningful structure and should be discarded. Returns: TRUE if the item was removed successfully, FALSE otherwise. Known bugs: Currently can't be used to remove a sub-menu item or a top-level menu. These can only be removed by clearing the menu strip using the @{" ClearMenus " Link ClearMenus} function and creating the menus again. See also: @{" AddMenuItem " Link AddMenuItem} @{" ClearMenus " Link ClearMenus} @{" DisableMenu " Link DisableMenu} @endnode @node SetWinMenuFn "SetWinMenuFn function" Function prototype: void SetWinMenuFn(GuiWindow *win, int (*fn) (GuiWindow*, struct MenuItem*)); Description: Set or change the function to be invoked when an action menu in the specified window is selected. This function allows the programmer to write his/her own function which will be called whenever the user selects an action menu in the specified window. Windows that share menus do not necessarily have to have the same menu function so if you want two windows to share the same menu function it is necessary to call SetWinMenuFn once for each window. Parameters: win: The Gui window whose menu function you wish to set. fn: A pointer to the menu function for the specified window. The function should have the following prototype: int MyWindowMenuFunction(GuiWindow *WhichWindow, struct MenuItem *WhichMenuItem); The function will be passed a pointer to the menu item that was selected and the window it was attached to. It should return either @{" GUI_CONTINUE " Link GuiContinueEnd} or @{" GUI_END " Link GuiContinueEnd}. Known bugs: None. See also: @{" AddMenu " Link AddMenu} @{" OpenGuiWindow " Link OpenGuiWindow} @{" ShareMenus " Link ShareMenus} @endnode @node ShareMenus "ShareMenus function" Function prototype: void ShareMenus(GuiWindow *dest, GuiWindow *source); Description: Causes a set of menus to be shared between two or more windows. When a number of windows share the same menu strip, most FoxGui menu functions which are applied to that menu strip will affect the menus in all of those windows (the only current exception being the function @{" SetWinMenuFn " Link SetWinMenuFn} which only affects the window passed as it's second parameter). For example, if windows A and B share the same menu strip and AddMenu is called to add a new top-level menu to window A, it will also be added to window B. In order to make Window B share menus already created for Window A, call ShareMenus(B, A). If window B already has menus they will be cleared. In order to then use the same menus for a third window C you could either use ShareMenus(C, B) or ShareMenus(C, A). Parameters: dest: A pointer to the Gui window to which the menus will be applied. source: A pointer to the Gui window whose existing menus are to be shared. Known bugs: The source window must have at least one top-level menu attached to it for ShareMenus to work. If it hasn't, the function won't cause them to share menus. As long as source has one top-level menu when ShareMenus is called, any other alterations to the menu structure of either window will affect both. See also: @{" AddMenu " Link AddMenu} @{" SetWinMenuFn " Link SetWinMenuFn} @endnode @node Buttons "FoxGui Button functions" Buttons are probably the most commonly used intuition "gadgets" so I've made them very simple. The functions below should all be obvious by their names. If not then you'll just have to read the function descriptions! Buttons can have images attached to them (drawn on them) - see the @{" AttachBitMapToControl " Link AttachBitMapToControl} function. The following button functions are currently available :- @{" DestroyAllButtons " Link DestroyAllButtons} @{" DestroyButton " Link DestroyButton} @{" DestroyWinButtons " Link DestroyWinButtons} @{" DisableAllButtons " Link DisableAllButtons} @{" DisableButton " Link DisableButton} @{" DisableWinButtons " Link DisableWinButtons} @{" EnableAllButtons " Link EnableAllButtons} @{" EnableButton " Link EnableButton} @{" EnableWinButtons " Link EnableWinButtons} @{" MakeButton " Link MakeButton} @{" RestoreButtonStatus " Link RestoreButtonStatus} @{" StoreButtonStatus " Link StoreButtonStatus} @endnode @node DestroyAllButtons "DestroyAllButtons function" Function prototype: void DestroyAllButtons(BOOL refresh); Description: Destroy all FoxGui buttons created by this application, freeing all resources. Parameters: refresh: If TRUE, the buttons will disappear (i.e. their imagery will be removed from the windows they were made in). You would typically set this to FALSE only if you were about to close the window anyway (there's no point in updating the button imagery for a window which is about to close since closing the window will remove the imagery). Known bugs: None. See also: @{" DestroyButton " Link DestroyButton} @{" DestroyWinButtons " Link DestroyWinButtons} @{" DisableAllButtons " Link DisableAllButtons} @{" MakeButton " Link MakeButton} @endnode @node DestroyButton "DestroyButton function" Function prototype: void DestroyButton(PushButton *b, BOOL refresh); Description: Destroy the specified button, freeing it's resources. Parameters: b: A pointer to the button to destroy. refresh: If TRUE, the button will disappear (i.e. it's imagery will be removed from the window it was made in). You would typically set this to FALSE only if you were about to close the window anyway (there's no point in updating the button imagery for a window which is about to close since closing the window will remove the imagery). Known bugs: None. See also: @{" Destroy " Link Destroy} @{" DestroyAllButtons " Link DestroyAllButtons} @{" DestroyWinButtons " Link DestroyWinButtons} @{" DisableButton " Link DisableButton} @{" MakeButton " Link MakeButton} @endnode @node DestroyWinButtons "DestroyWinButtons function" Function prototype: void DestroyWinButtons(GuiWindow *w, BOOL refresh); Description: Destroy all buttons in the specified window. Parameters: w: A pointer to the Gui window whose buttons are to be destroyed. refresh: If TRUE, the buttons will disappear (i.e. their imagery will be removed from the window). You would typically set this to FALSE only if you were about to close the window anyway (there's no point in updating the button imagery for a window which is about to close since closing the window will remove the imagery). Known bugs: None. See also: @{" DestroyAllButtons " Link DestroyAllButtons} @{" DestroyButton " Link DestroyButton} @{" DisableWinButtons " Link DisableWinButtons} @{" MakeButton " Link MakeButton} @endnode @node DisableAllButtons "DisableAllButtons function" Function prototype: void DisableAllButtons(void); Description: Disable all FoxGui buttons. When a button is disabled it looks the same as an enabled button except that the button face is shaded and the imagary won't change if the user clicks on the button (i.e. the button won't look as though it's been pressed). When a button is disabled, the user defined function attached to it will not be called if the button is clicked. Known bugs: None. See also: @{" DestroyAllButtons " Link DestroyAllButtons} @{" DisableButton " Link DisableButton} @{" DisableWinButtons " Link DisableWinButtons} @{" EnableAllButtons " Link EnableAllButtons} @{" MakeButton " Link MakeButton} @{" RestoreButtonStatus " Link RestoreButtonStatus} @{" StoreButtonStatus " Link StoreButtonStatus} @endnode @node DisableButton "DisableButton function" Function prototype: void DisableButton(PushButton *Bptr); Description: Disable the specified FoxGui button. When a button is disabled it looks the same as an enabled button except that the button face is shaded and the imagary won't change if the user clicks on the button (i.e. the button won't look as though it's been pressed). When a button is disabled, the user defined function attached to it will not be called if the button is clicked. Parameters: Bptr: A pointer to the FoxGui button to be disabled. Known bugs: None. See also: @{" DestroyButton " Link DestroyButton} @{" DisableAllButtons " Link DisableAllButtons} @{" DisableButton " Link DisableButton} @{" DisableControl " Link DisableControl} @{" EnableButton " Link EnableButton} @{" MakeButton " Link MakeButton} @{" RestoreButtonStatus " Link RestoreButtonStatus} @{" StoreButtonStatus " Link StoreButtonStatus} @endnode @node DisableWinButtons "DisableWinButtons function" Function prototype: void DisableWinButtons(GuiWindow *w); Description: Disable all FoxGui buttons in the specified FoxGui window. When a button is disabled it looks the same as an enabled button except that the button face is shaded and the imagary won't change if the user clicks on the button (i.e. the button won't look as though it's been pressed). When a button is disabled, the user defined function attached to it will not be called if the button is clicked. Parameters: w: A pointer to an open Gui window whose buttons are to be disabled. Known bugs: None. See also: @{" DestroyWinButtons " Link DestroyWinButtons} @{" DisableAllButtons " Link DisableAllButtons} @{" DisableButton " Link DisableButton} @{" EnableWinButtons " Link EnableWinButtons} @{" MakeButton " Link MakeButton} @{" RestoreButtonStatus " Link RestoreButtonStatus} @{" StoreButtonStatus " Link StoreButtonStatus} @endnode @node EnableAllButtons "EnableAllButtons function" Function prototype: void EnableAllButtons(void); Description: Enable all FoxGui buttons in the current application. Buttons are automatically enabled when they are created so it is only necessary to call this function to enable all buttons which have previously been disabled. Known bugs: None. See also: @{" DisableAllButtons " Link DisableAllButtons} @{" EnableButton " Link EnableButton} @{" EnableWinButtons " Link EnableWinButtons} @endnode @node EnableButton "EnableButton function" Function prototype: void EnableButton(PushButton *Bptr); Description: Enable the specified FoxGui button. Parameters: Bptr: A pointer to an existing FoxGui button to enable. If the button is already enabled, this function will have no effect. If the button is currently disabled, it will become enabled and it's imagery will revert to that of an enabled button (see @{" DisableButton " Link DisableButton} for details). Known bugs: None. See also: @{" DisableButton " Link DisableButton} @{" EnableAllButtons " Link EnableAllButtons} @{" EnableControl " Link EnableControl} @{" EnableWinButtons " Link EnableWinButtons} @endnode @node EnableWinButtons "EnableWinButtons function" Function prototype: void EnableWinButtons(GuiWindow *w); Description: Enable all FoxGui buttons in the specified FoxGui window, reverting their imagery to the enabled state. Parameters: w: A pointer to an open FoxGui window. Known bugs: None. See also: @{" DisableWinButtons " Link DisableWinButtons} @{" EnableAllButtons " Link EnableAllButtons} @{" EnableButton " Link EnableButton} @endnode @node MakeButton "MakeButton function" Function prototype: PushButton *MakeButton(void *Parent, char *name, int left, int top, int width, int height, int tcol, int bcol, int key, struct Border *cb, int (*callfn) (PushButton*), short flags); Description: Create a FoxGui button in the specified window or frame with the attributes specified. The button will automatically be enabled and when the user clicks the button the function specified in callfn will be invoked and passed a pointer to the button that was clicked. Parameters: Parent: A pointer to an open FoxGui window or frame in which to place the new button. name: The text to appear as the buttons caption. If you don't want a caption, set this to "" or NULL. If you want the button to have a hot-key (a key that is used to activate the button from the keyboard) then you should pass the relevant character in the "key" parameter. If that key is one of the characters of the buttons caption then you can preceed that character by an underscore ("_") and that character will be underlined in the button caption. For example, for an okay button you might pass "O_kay" in which case the k will be underlined. If the caption for the button is too long to fit it then it will be truncated - the caption will never extend beyond the button's border. If the button gets resized (due to a window being resized) then more of the caption may become visible - i.e. FoxGui remembers the whole caption not just the visible bit. left: The coordinate of the left edge of the button relative to the left edge of the window/frame. If you prefer, you can specify a negative value here and that will be taken to mean an offset of the left hand edge of the button from the right hand edge of the window/frame. If the window/frame gets resized, this will also cause the button to move to remain at the same offset from the right hand edge of the window/frame. top: The coordinate of the top edge of the button relative to the top edge of the window/frame. Note that this is from the very top of a window so a y coordinate of 0 would cause the button to be at least partly obscured by the window's title bar if it had one. If you prefer, you can specify a negative value here and that will be taken to mean an offset of the top edge of the button from the bottom edge of the window/frame. If the window/frame gets resized, this will also cause the button to move to remain at the same offset from the bottom of the window/frame. width: The width of the button in pixels. height: The height of the button in pixels. tcol: The text colour of the button. bcol: The background colour of the button. key: The button's hot key. For example, to make the hot key the letter k, pass 'k'. cb: If you want your button to have some form of custom imagery not directly supported by MakeButton, you can create your own intuition border structure and pass a pointer to it as cb. This will be displayed as well as the standard button border and caption (if there is one). It's main use is to draw a simple picture on the button in place of a caption. The caption is ommitted by passing the name as "". callfn: A pointer to the function to be called when the button is clicked. The function should have the following prototype: int MyButtonFunction (PushButton*); When it is invoked, it will be passed a pointer to the button that was clicked (this allows you to have one button function which handles all of your buttons if you wish. Of course you could alternatively have a different function for each button in which case the parameter would be redundant). It should return either @{" GUI_CONTINUE " Link GuiContinueEnd} or @{" GUI_END " Link GuiContinueEnd}. flags: The following flags are available for buttons: BN_CLEAR, BN_AR, BN_STD, BN_OKAY, BN_CANCEL and @{" S_AUTO_SIZE " Link S_AUTO_SIZE}. If BN_CLEAR is set then the background colour of the button will be the same colour as the window that the button is created in and the bcol parameter will be ignored. If you want to attach an image to a button then the button must be created with this flag specified. Clear buttons are drawn more quickly than coloured buttons. If you don't specify the BN_CLEAR flag but the bcol parameter is the same as the background colour of the window then the button won't be treated as clear so it will take marginally longer to refresh. If buttons are not clear then the whole button area is refreshed when necessary. If they are clear then only the border is refreshed. BN_OKAY and BN_CANCEL allow either the return key or the escape key respecively to be used as an extra hot-key for the button. An example of how you might use these would be some sort of preferences window where the user can modify several controls (eg tick boxes, drop-down list boxes, edit boxes etc) and then either cancel or accept the action. You might have two buttons in the window labelled "Okay" and "Cancel" which have O and C as their respective hot-keys but where the Okay button has BN_OKAY set and the Cancel button has BN_CANCEL set so that the preferences could also be accepted or cancelled by pressing return or escape. The other two flags are mutually exclusive. BN_STD specifies that this is a standard button, BN_AR specifies that it is an auto-repeating button. If you click on a standard button, the function is activated when the button is released. If the mousepointer is moved off the button before it is released then the function isn't called. An auto-repeat button is activated immediately that the button is clicked and is repeatedly activated while the button is held down. The delay between each activation of the button can be set by calling @{" SetDelay " Link SetDelay} and @{" SetPeriod " Link SetPeriod}. Returns: If successful, a pointer to the new FoxGui button is returned. If unsuccessful, NULL is returned. Known bugs: None. See also: @{" DestroyButton " Link DestroyButton} @{" DisableButton " Link DisableButton} @{" EnableButton " Link EnableButton} @{" RestoreButtonStatus " Link RestoreButtonStatus} @{" SetDelay " Link SetDelay} @{" SetPeriod " Link SetPeriod} @{" StoreButtonStatus " Link StoreButtonStatus} @{" AttachBitMapToControl " Link AttachBitMapToControl} @endnode @node RestoreButtonStatus "RestoreButtonStatus function" Function prototype: void RestoreButtonStatus(void); Description: Restore the status of each FoxGui button. This can only be called after a call to @{" StoreButtonStatus " Link StoreButtonStatus}. Known bugs: None. See also: @{" StoreButtonStatus " Link StoreButtonStatus} @endnode @node StoreButtonStatus "StoreButtonStatus function" Function prototype: void StoreButtonStatus(void); Description: Stores the status (enabled or disabled) of every FoxGui button in the application. You would typically do this if you wanted to temporarily disable all of the buttons and then at a later point return each button to it's previous state without having to know what the status of each button was and reset them individually. Your code might look like this: StoreButtonStatus(); DisableAllButtons(); // Some code which mustn't be interupted by button clicks // ... // End of uninteruptable code. RestoreButtonStatus(); Known bugs: None. See also: @{" RestoreButtonStatus " Link RestoreButtonStatus} @endnode @node BoolGads "FoxGui Boolean Gadget functions" Strictly, buttons are a type of boolean gadget but there are so many button functions that I gave them a topic of their own. The other types of boolean gadget are dealt with here. The other boolean gadgets supported by FoxGui are tick-boxes and radio buttons. A Tick-box is a small square button with a tick in it (or not as the case may be). You make the tick appear or disappear by clicking on the button. Usually a tick specifies that some option is turned on and lack of a tick means that it is turned off. Radio buttons are another type of boolean gadget. These are grouped together and selecting one causes any other in the same group to become de-selected (i.e. they are mutually exclusive) like the buttons on the front of old radios if you are old enough to remember them! The following boolean gadget functions are currently available :- @{" ActiveRadioButton " Link ActiveRadioButton} @{" DestroyAllRadioButtons " Link DestroyAllRadioButtons} @{" DestroyAllTickBoxes " Link DestroyAllTickBoxes} @{" DestroyRadioButton " Link DestroyRadioButton} @{" DestroyTickBox " Link DestroyTickBox} @{" DestroyWinRadioButtons " Link DestroyWinRadioButtons} @{" DestroyWinTickBoxes " Link DestroyWinTickBoxes} @{" DisableRadioButton " Link DisableRadioButton} @{" DisableTickBox " Link DisableTickBox} @{" EnableRadioButton " Link EnableRadioButton} @{" EnableTickBox " Link EnableTickBox} @{" MakeRadioButton " Link MakeRadioButton} @{" MakeTickBox " Link MakeTickBox} @{" TickBoxValue " Link TickBoxValue} @endnode @node ActiveRadioButton "ActiveRadioButton function" Function prototype: RadioButton *ActiveRadioButton(RadioButton *rb); Description: Given a pointer to any FoxGui radio button, this function returns a pointer to the currently selected radio button in that group. Parameters: rb: A pointer to a FoxGui radio button. Returns: A pointer to the currently selected radio button in the same group as the radio button passed as a parameter. If no radio button is selected in that group or if an error occurs, this function returns NULL. Known bugs: None. See also: @{" MakeRadioButton " Link MakeRadioButton} @endnode @node DestroyAllRadioButtons "DestroyAllRadioButtons function" Function prototype: void DestroyAllRadioButtons(BOOL refresh); Description: Destroys all FoxGui radio buttons in the current application. Parameters: refresh: If TRUE, refresh the windows containing the radio-buttons so that they visibly disappear. Known bugs: None. See also: @{" DestroyRadioButton " Link DestroyRadioButton} @{" DestroyWinRadioButtons " Link DestroyWinRadioButtons} @{" MakeRadioButton " Link MakeRadioButton} @endnode @node DestroyAllTickBoxes "DestroyAllTickBoxes function" Function prototype: void DestroyAllTickBoxes(BOOL refresh); Description: Destroy all FoxGui tick boxes and free all associated resources. Parameters: refresh: Refresh the screen display? (TRUE or FALSE). It would only be useful not to refresh the screen display if, for example, you are about to close a window and are destroying all of the gadgets in the window. In this case it would be quicker not to redraw the window display after each gadget is removed. Known bugs: None. See also: @{" DestroyTickBox " Link DestroyTickBox} @{" DestroyWinTickBoxes " Link DestroyWinTickBoxes} @{" MakeTickBox " Link MakeTickBox} @{" TickBoxValue " Link TickBoxValue} @endnode @node DestroyRadioButton "DestroyRadioButton function" Function prototype: void DestroyRadioButton(RadioButton *rb, BOOL refresh); Description: Destroys the specified FoxGui radio button. Parameters: rb: A pointer to the FoxGui radio button to destroy. refresh: If TRUE, refresh the window containing the radio button so that it visibly disappears. If you are about to close the window then it is quicker not to refresh it first. Known bugs: None. See also: @{" Destroy " Link Destroy} @{" DestroyAllRadioButtons " Link DestroyAllRadioButtons} @{" DestroyWinRadioButtons " Link DestroyWinRadioButtons} @{" MakeRadioButton " Link MakeRadioButton} @endnode @node DestroyTickBox "DestroyTickBox function" Function prototype: void DestroyTickBox(TickBox *tb, BOOL refresh); Description: Destroy the specified tick box and free all resources used by it. Parameters: tb: A pointer to an existing Tick Box to be destroyed. refresh: Refresh the screen display? (TRUE or FALSE). It would only be useful not to refresh the screen display if, for example, you are about to close a window and are destroying all of the gadgets in the window. In this case it would be quicker not to redraw the window display after each gadget is removed. Known bugs: None. See also: @{" Destroy " Link Destroy} @{" DestroyAllTickBoxes " Link DestroyAllTickBoxes} @{" DestroyWinTickBoxes " Link DestroyWinTickBoxes} @{" MakeTickBox " Link MakeTickBox} @endnode @node DestroyWinRadioButtons "DestroyWinRadioButtons function" Function prototype: void DestroyWinRadioButtons(GuiWindow *gw, BOOL refresh); Description: Destroy all FoxGui radio buttons in the specified FoxGui window. Parameters: gw: A pointer to an open FoxGui window whose radio buttons are to be destroyed. refresh: If TRUE, refresh the window so that the radio buttons disappear. If you are about to close the window then this may as well be FALSE as it's quicker if you don't refresh the window. Known bugs: None. See also: @{" DestroyAllRadioButtons " Link DestroyAllRadioButtons} @{" DestroyRadioButton " Link DestroyRadioButton} @{" MakeRadioButton " Link MakeRadioButton} @endnode @node DestroyWinTickBoxes "DestroyWinTickBoxes function" Function prototype: void DestroyWinTickBoxes(GuiWindow *gw, BOOL refresh); Description: Destroy all FoxGui tick boxes in the specified open FoxGui window and free all associated resources. Parameters: gw: A pointer to an open FoxGui window whose tick boxes are to be destroyed. refresh: Refresh the screen display? (TRUE or FALSE). It would only be useful not to refresh the screen display if, for example, you are about to close a window and are destroying all of the gadgets in the window. In this case it would be quicker not to redraw the window display after each gadget is removed. Known bugs: None. See also: @{" DestroyAllTickBoxes " Link DestroyAllTickBoxes} @{" DestroyTickBox " Link DestroyTickBox} @{" MakeTickBox " Link MakeTickBox} @{" TickBoxValue " Link TickBoxValue} @endnode @node DisableRadioButton "DisableRadioButton function" Function prototype: void DisableRadioButton(RadioButton *rb); Description: Disables the specified FoxGui radio button. When radio buttons are disabled they become shaded and will not respond if the user clicks on them. Parameters: rb: A pointer to the FoxGui radio button to disable. Known bugs: None. See also: @{" DestroyRadioButton " Link DestroyRadioButton} @{" DisableControl " Link DisableControl} @{" EnableRadioButton " Link EnableRadioButton} @{" MakeRadioButton " Link MakeRadioButton} @endnode @node DisableTickBox "DisableTickBox function" Function prototype: void DisableTickBox(TickBox *tb); Description: Disables the specified FoxGui tick box. When tick boxes are disabled they become shaded and will not respond if the user clicks on them. Parameters: tb: A pointer to the FoxGui tick box to disable. Known bugs: None. See also: @{" DestroyTickBox " Link DestroyTickBox} @{" DisableControl " Link DisableControl} @{" EnableTickBox " Link EnableTickBox} @{" MakeTickBox " Link MakeTickBox} @endnode @node EnableRadioButton "EnableRadioButton function" Function prototype: void EnableRadioButton(RadioButton *rb); Description: Enables a disabled FoxGui radio button. The radio buttons imagery will return to normal and it will respond when clicked. Parameters: rb: A pointer to the FoxGui radio button to enable. Known bugs: None. See also: @{" DisableRadioButton " Link DisableRadioButton} @{" EnableControl " Link EnableControl} @{" MakeRadioButton " Link MakeRadioButton} @endnode @node EnableTickBox "EnableTickBox function" Function prototype: void EnableTickBox(TickBox *tb); Description: Enables a disabled FoxGui tick box. The tick boxes imagery will return to normal and it will respond when clicked. Parameters: tb: A pointer to the FoxGui tick box to enable. Known bugs: None. See also: @{" DisableTickBox " Link DisableTickBox} @{" EnableControl " Link EnableControl} @{" MakeTickBox " Link MakeTickBox} @endnode @node MakeRadioButton "MakeRadioButton function" Function prototype: RadioButton *MakeRadioButton(void *Parent, RadioButton *MutEx, int left, int top, int width, int height, int fillcol, char *caption, struct TextAttr *font, int captioncol, int (*callfn) (RadioButton*), int flags); Description: Make a new FoxGui radio button in the specified FoxGui window or frame. Parameters: Parent: A pointer to an open FoxGui window or frame in which to create the new radio button. MutEx: A pointer to another radio button which you want to be mutually exclusive with this one (i.e. in the same group). When creating the first radio button in a group, set this parameter to NULL. When creating subsequent radio buttons in the group, this parameter can point to any one of the radio buttons already created and the whole group will be mutually exclusive (i.e. selecting any one member in the group will cause any other button in the group that was previously selected to become un-selected). left: The distance in pixels between the left edge of the window/frame and the left edge of the selectable part of the radio button. Remember to leave enough room for the caption on either the left or right of the radio button itself. top: The distance in pixels between the top edge of the window/frame and the top edge of the radio button. width: The width of the selectable part of the radio button (in pixels). height: The height of the radio button in pixels. fillcol: When a radio button is selected, the centre of the button gets filled in the colour specified in this parameter. Unselected radio buttons are not filled. caption: A NULL terminated text string to appear to the left or right of the radio button (see the flags parameter below). Use NULL if you don't want a caption. font: A pointer to an Intuition TextAttr structure describing the font to use for the caption. If NULL, the font for the window is used (the window inherits its font from the screen). captioncol: The colour to use for the caption. callfn: A function to call when this radio button is selected by the user. The function will be passed a pointer to the radio button selected so if you like you can use the same function for all of the radio buttons in a group or even all of the radio buttons in an application. If you don't want to perform any special action immediately that the radio button is selected, you can pass NULL for this parameter. If you do specify a function, it should have the following prototype :- int MyRadioButtonFn (RadioButton *WhichRadioButton); and should return either @{" GUI_CONTINUE " Link GuiContinueEnd} or @{" GUI_END " Link GuiContinueEnd}. flags: Currently, there are only four valid flags for radio buttons: BG_SELECTED causes the radio button to be the initially selected radio button in the group. Obviously you should only set this flag for one radio button in each group. BG_CAPTION_LEFT prints the caption to the left of the radio button, BG_CAPTION_RIGHT prints the caption to the right of the radio button. If neither BG_CAPTION_LEFT or BG_CAPTION_RIGHT is specified, the default is BG_CAPTION_LEFT. Radio buttons will auto-size when their window is resized if the @{" S_AUTO_SIZE " Link S_AUTO_SIZE} flag is selected. Returns: If successful, a pointer to the new radio button. If not, NULL. Known bugs: None. See also: @{" ActiveRadioButton " Link ActiveRadioButton} @{" DestroyAllRadioButtons " Link DestroyAllRadioButtons} @{" DestroyRadioButton " Link DestroyRadioButton} @{" DestroyWinRadioButtons " Link DestroyWinRadioButtons} @endnode @node TickBoxValue "TickBoxValue function" Function prototype: BOOL TickBoxValue(TickBox *tb); Description: Find the current value of the specified tick box. Parameters: tb: The tick box whose value you want to know. Returns: TRUE if the tick box is ticked, FALSE otherwise. Known bugs: None. See also: @{" DestroyTickBox " Link DestroyTickBox} @{" MakeTickBox " Link MakeTickBox} @endnode @node MakeTickBox "MakeTickBox function" Function prototype: TickBox *MakeTickBox(void *Parent, int left, int top, int width, int height, int tickcol, int fillcol, char *caption, struct TextAttr *font, int captioncol, int (*callfn) (TickBox*), int flags); Description: Make a new tick box gadget. Parameters: Parent: The Gui window or frame in which the new tick box is to be created. left: The left edge of the tick box in pixels from the left edge of the window/frame. top: The top edge of the tick box in pixels from the top edge of the window/frame. width: The width of the tick box in pixels. height: The height of the tick box in pixels. tickcol: The colour to use when drawing the tick in the tick box. fillcol: The colour of the tick box. This is ignored if the BG_CLEAR flag is specified in the flags parameter. caption: A NULL terminated string to print next to the tick box. If you do not want a caption for this tick box then this parameter should be NULL. font: The font to use for the caption. If NULL, the font for the specified window is used (the window inherits the screen font). captioncol: The colour in which the caption will be printed. callfn: A function to call whenever the user changes the state of the tick box by clicking on it with the mouse. The prototype for the function should be as follows: int MyTickBoxFunction(TickBox *WhichTickBox); The function will be passed a pointer to the tick box that was clicked and should return either @{" GUI_CONTINUE " Link GuiContinueEnd} or @{" GUI_END " Link GuiContinueEnd}. flags: Currently, there are only five valid flags for tick boxes :- BG_SELECTED causes the tick box to be ticked initially. BG_CAPTION_LEFT prints the caption to the left of the tick box, BG_CAPTION_RIGHT prints the caption to the right of the tick box. If neither BG_CAPTION_LEFT or BG_CAPTION_RIGHT is specified, the default is BG_CAPTION_LEFT. The BG_CLEAR flag causes the tick box to be clear (i.e. the same colour as the window). Clear tick boxes are drawn and refreshed more quickly than filled ones. The @{" S_AUTO_SIZE " Link S_AUTO_SIZE} flag causes the tick box to auto-size. Returns: If successful, a pointer to the new tick box is returned. If the function fails then NULL is returned. Known bugs: None. See also: @{" DestroyAllTickBoxes " Link DestroyAllTickBoxes} @{" DestroyTickBox " Link DestroyTickBox} @{" DestroyWinTickBoxes " Link DestroyWinTickBoxes} @{" TickBoxValue " Link TickBoxValue} @endnode @node EditBoxes "FoxGui Editbox functions" Edit boxes are Intuition string gadgets. They are containers into which the user can type text. If there are several in a window (and you are using OS version 2.0 or above) you can switch between edit boxes using tab and shift-tab. FoxGui supplies three default filters for edit boxes: TEXT, INT and FLOAT. INT edit boxes are for capturing integral numbers. The user can type digits and a preceeding + or - sign only. All other characters are rejected. FLOAT also allows the . symobol allowing floating point numbers to be entered and TEXT allows anything to be typed. The default filter is TEXT and is supported under all versions of the Amiga OS. The INT filter is supported from release 2.00 onwards and the FLOAT filter is supported in Intuition version 36 and above. In a FLOAT filtered edit box, you can also specify the number of digits allowed after the decimal point using @{" SetEditBoxDP " Link SetEditBoxDP}. Functions are available for setting the text in edit boxes as well as for retrieving text or numbers that the user has entered. The following editbox functions are currently available :- @{" DestroyAllEditBoxes " Link DestroyAllEditBoxes} @{" DestroyEditBox " Link DestroyEditBox} @{" DestroyWinEditBoxes " Link DestroyWinEditBoxes} @{" DisableAllEditBoxes " Link DisableAllEditBoxes} @{" DisableEditBox " Link DisableEditBox} @{" DisableWinEditBoxes " Link DisableWinEditBoxes} @{" EnableAllEditBoxes " Link EnableAllEditBoxes} @{" EnableEditBox " Link EnableEditBox} @{" EnableWinEditBoxes " Link EnableWinEditBoxes} @{" GetEditBoxFloat " Link GetEditBoxFloat} @{" GetEditBoxInt " Link GetEditBoxInt} @{" GetEditBoxText " Link GetEditBoxText} @{" MakeEditBox " Link MakeEditBox} @{" RefreshEditBox " Link RefreshEditBox} @{" RestoreEditBoxStatus " Link RestoreEditBoxStatus} @{" SetEditBoxCols " Link SetEditBoxCols} @{" SetEditBoxDP " Link SetEditBoxDP} @{" SetEditBoxFloat " Link SetEditBoxFloat} @{" SetEditBoxFocus " Link SetEditBoxFocus} @{" SetEditBoxInt " Link SetEditBoxInt} @{" SetEditBoxText " Link SetEditBoxText} @{" StoreEditBoxStatus " Link StoreEditBoxStatus} The following editbox operations are defined as macros :- @{" GetEditBoxID " Link GetEditBoxID} @endnode @node DestroyAllEditBoxes "DestroyAllEditBoxes function" Function prototype: void DestroyAllEditBoxes(BOOL refresh); Description: Destroy all FoxGui edit boxes in the current application and free all associated resources. Parameters: refresh: If TRUE, the edit box imagery is removed from the window. If FALSE, the edit boxes are still destroyed but their imagery remains. Removing the imagery is relatively slow, so if you are about to close the window then there is little point in refreshing the imagery first. Known bugs: None. See also: @{" DestroyEditBox " Link DestroyEditBox} @{" DestroyWinEditBoxes " Link DestroyWinEditBoxes} @{" DisableAllEditBoxes " Link DisableAllEditBoxes} @{" EnableAllEditBoxes " Link EnableAllEditBoxes} @{" MakeEditBox " Link MakeEditBox} @{" RefreshEditBox " Link RefreshEditBox} @endnode @node DestroyEditBox "DestroyEditBox function" Function prototype: void DestroyEditBox(EditBox *p, BOOL refresh); Description: Destroy the specified edit box and free all associated resources. Parameters: p: A pointer to the edit box to be destroyed. refresh: If TRUE, the edit box imagery is removed from the window. If FALSE, the edit box is still destroyed but it's imagery remains. Removing the imagery is relatively slow, so if you are about to close the window then there is little point in refreshing the imagery first. Known bugs: None. See also: @{" Destroy " Link Destroy} @{" DestroyAllEditBoxes " Link DestroyAllEditBoxes} @{" DestroyWinEditBoxes " Link DestroyWinEditBoxes} @{" DisableEditBox " Link DisableEditBox} @{" EnableEditBox " Link EnableEditBox} @{" MakeEditBox " Link MakeEditBox} @{" RefreshEditBox " Link RefreshEditBox} @endnode @node DestroyWinEditBoxes "DestroyWinEditBoxes function" Function prototype: void DestroyWinEditBoxes(GuiWindow *c, BOOL refresh); Description: Destroy all FoxGui editboxes in the specified window and free all associated resources. Parameters: c: A pointer to an open FoxGui window, possibly containing edit boxes. refresh: If TRUE, the edit box imagery is removed from the window. If FALSE, the edit boxes are still destroyed but their imagery remains. Removing the imagery is relatively slow, so if you are about to close the window then there is little point in refreshing the imagery first. Known bugs: None. See also: @{" DestroyAllEditBoxes " Link DestroyAllEditBoxes} @{" DestroyEditBox " Link DestroyEditBox} @{" DisableWinEditBoxes " Link DisableWinEditBoxes} @{" EnableWinEditBoxes " Link EnableWinEditBoxes} @{" MakeEditBox " Link MakeEditBox} @{" RefreshEditBox " Link RefreshEditBox} @endnode @node DisableAllEditBoxes "DisableAllEditBoxes function" Function prototype: void DisableAllEditBoxes(BOOL redraw); Description: Disable all FoxGui edit boxes in the current application. These can later be re-enabled by calling one of three functions (see below). Parameters: redraw: If TRUE, refresh the edit box imagery. Disabled edit boxes are shaded to show that input is not currently possible. Disabling edit boxes is faster if redraw is FALSE but this could be confusing because the edit box will then appear enabled when it is actually disabled. You can refresh an edit box at any time by calling @{" RefreshEditBox " Link RefreshEditBox}. Known bugs: None. See also: @{" DisableEditBox " Link DisableEditBox} @{" DisableWinEditBoxes " Link DisableWinEditBoxes} @{" EnableAllEditBoxes " Link EnableAllEditBoxes} @{" EnableEditBox " Link EnableEditBox} @{" EnableWinEditBoxes " Link EnableWinEditBoxes} @{" RefreshEditBox " Link RefreshEditBox} @{" RestoreEditBoxStatus " Link RestoreEditBoxStatus} @{" StoreEditBoxStatus " Link StoreEditBoxStatus} @endnode @node DisableEditBox "DisableEditBox function" Function prototype: void DisableEditBox(EditBox *p, BOOL redraw); Description: Disable the specified edit box, preventing the user from entering any text into it. Parameters: p: A pointer to the edit box to be disabled. redraw: If TRUE, refresh the edit box imagery. Disabled edit boxes are shaded to show that input is not currently possible. Disabling edit boxes is faster if redraw is FALSE but this could be confusing because the edit box will then appear enabled when it is actually disabled. You can refresh an edit box at any time by calling @{" RefreshEditBox " Link RefreshEditBox}. Known bugs: None. See also: @{" DisableAllEditBoxes " Link DisableAllEditBoxes} @{" DisableControl " Link DisableControl} @{" DisableWinEditBoxes " Link DisableWinEditBoxes} @{" EnableEditBox " Link EnableEditBox} @{" RefreshEditBox " Link RefreshEditBox} @{" RestoreEditBoxStatus " Link RestoreEditBoxStatus} @{" StoreEditBoxStatus " Link StoreEditBoxStatus} @endnode @node DisableWinEditBoxes "DisableWinEditBoxes function" Function prototype: void DisableWinEditBoxes(GuiWindow *c, BOOL redraw); Description: Disable all FoxGui edit boxes in the specified FoxGui window, preventing the user from entering any text into them. Parameters: c: A pointer to the FoxGui window whose edit boxes are to be disabled. redraw: If TRUE, refresh the edit box imagery. Disabled edit boxes are shaded to show that input is not currently possible. Disabling edit boxes is faster if redraw is FALSE but this could be confusing because the edit box will then appear enabled when it is actually disabled. You can refresh an edit box at any time by calling @{" RefreshEditBox " Link RefreshEditBox}. Known bugs: None. See also: @{" DisableAllEditBoxes " Link DisableAllEditBoxes} @{" DisableEditBox " Link DisableEditBox} @{" EnableWinEditBoxes " Link EnableWinEditBoxes} @{" RefreshEditBox " Link RefreshEditBox} @{" RestoreEditBoxStatus " Link RestoreEditBoxStatus} @{" StoreEditBoxStatus " Link StoreEditBoxStatus} @endnode @node EnableAllEditBoxes "EnableAllEditBoxes function" Function prototype: void EnableAllEditBoxes(BOOL redraw); Description: Enable all edit boxes in the current application. It is not necessary to enable edit boxes when they are first created as they are enabled by default. Parameters: redraw: If TRUE, refresh the edit box imagery. Disabled edit boxes are shaded to show that input is not currently possible. Enabling edit boxes is faster if redraw is FALSE but this could be confusing because the edit box will then appear disabled when it is actually enabled. You can refresh an edit box at any time by calling @{" RefreshEditBox " Link RefreshEditBox}. Known bugs: None. See also: @{" DisableAllEditBoxes " Link DisableAllEditBoxes} @{" EnableEditBox " Link EnableEditBox} @{" EnableWinEditBoxes " Link EnableWinEditBoxes} @{" RefreshEditBox " Link RefreshEditBox} @{" RestoreEditBoxStatus " Link RestoreEditBoxStatus} @{" StoreEditBoxStatus " Link StoreEditBoxStatus} @endnode @node EnableEditBox "EnableEditBox function" Function prototype: void EnableEditBox(EditBox *p, BOOL redraw); Description: Enable the specified edit box. There is no need to enable an edit box when it is created as this is the default status. Parameters: p: A pointer to the edit box to enable. redraw: If TRUE, refresh the edit box imagery. Disabled edit boxes are shaded to show that input is not currently possible. Enabling edit boxes is faster if redraw is FALSE but this could be confusing because the edit box will then appear disabled when it is actually enabled. You can refresh an edit box at any time by calling @{" RefreshEditBox " Link RefreshEditBox}. Known bugs: None. See also: @{" DisableEditBox " Link DisableEditBox} @{" EnableAllEditBoxes " Link EnableAllEditBoxes} @{" EnableControl " Link EnableControl} @{" EnableWinEditBoxes " Link EnableWinEditBoxes} @{" RefreshEditBox " Link RefreshEditBox} @{" RestoreEditBoxStatus " Link RestoreEditBoxStatus} @{" StoreEditBoxStatus " Link StoreEditBoxStatus} @endnode @node EnableWinEditBoxes "EnableWinEditBoxes function" Function prototype: void EnableWinEditBoxes(GuiWindow *c, BOOL redraw); Description: Enable all FoxGui edit boxes in the specified FoxGui window. It is not necessary to enable edit boxes when they are first created as they are enabled by default. Parameters: c: A pointer to the FoxGui window whose edit boxes are to be enabled. redraw: If TRUE, refresh the edit box imagery. Disabled edit boxes are shaded to show that input is not currently possible. Enabling edit boxes is faster if redraw is FALSE but this could be confusing because the edit box will then appear disabled when it is actually enabled. You can refresh an edit box at any time by calling @{" RefreshEditBox " Link RefreshEditBox}. Known bugs: None. See also: @{" DisableWinEditBoxes " Link DisableWinEditBoxes} @{" EnableAllEditBoxes " Link EnableAllEditBoxes} @{" EnableEditBox " Link EnableEditBox} @{" RefreshEditBox " Link RefreshEditBox} @{" RestoreEditBoxStatus " Link RestoreEditBoxStatus} @{" StoreEditBoxStatus " Link StoreEditBoxStatus} @endnode @node GetEditBoxFloat "GetEditBoxFloat function" Function prototype: float GetEditBoxFloat(EditBox *p); Description: Converts the text in the specified edit box into a floating point number and returns the result. On Intuition version 36 or higher, an edit box created with type FLOAT_EDIT is filtered so that a user can only type floating point numbers into it. In this case GetEditBoxFloat will usually succeed (note that even under these circumstances it is possible for a FLOAT_EDIT edit box to contain text which cannot be interpreted as a floating point number but only if it has been set from within the program by use of the function @{" SetEditBoxText " Link SetEditBoxText}. If the number cannot be interpreted as a floating point number then anything may be returned. You can control the number of decimal places that the user can type into a FLOAT_EDIT edit box using the function @{" SetEditBoxDP " Link SetEditBoxDP}. Parameters: p: A pointer to the edit box. Returns: A floating point number whose value is the text in the specified edit box. Known bugs: None. See also: @{" GetEditBoxInt " Link GetEditBoxInt} @{" GetEditBoxText " Link GetEditBoxText} @{" MakeEditBox " Link MakeEditBox} @{" SetEditBoxDP " Link SetEditBoxDP} @{" SetEditBoxFloat " Link SetEditBoxFloat} @endnode @node GetEditBoxInt "GetEditBoxInt function" Function prototype: int GetEditBoxInt(EditBox *p); Description: Converts the text in the specified edit box into an integer and returns the result. On OS version 2.00 or higher, an edit box created with type INT_EDIT is filtered so that a user can only type integral numbers into it. In this case GetEditBoxInt will usually succeed (note that even under these circumstances it is possible for an INT_EDIT edit box to contain text which cannot be interpreted as an integer but only if it has been set from within the program by use of the functions @{" SetEditBoxText " Link SetEditBoxText} or @{" SetEditBoxFloat " Link SetEditBoxFloat}. If the number cannot be interpreted as an integer then anything may be returned. Parameters: p: A pointer to the edit box. Returns: An integer whose value is the text in the specified edit box. Known bugs: None. See also: @{" GetEditBoxFloat " Link GetEditBoxFloat} @{" GetEditBoxText " Link GetEditBoxText} @{" MakeEditBox " Link MakeEditBox} @{" SetEditBoxInt " Link SetEditBoxInt} @endnode @node GetEditBoxText "GetEditBoxText function" Function prototype: char *GetEditBoxText(EditBox *p); Description: Get the current text in the specified edit box. Parameters: p: A pointer to the edit box. Returns: A pointer to a NULL terminated text string which is the text contained in the specified edit box. The pointer returned is a pointer to the actual buffer used by the edit box so you should never directly modify this string in any way. If you keep a copy of the pointer you should also remember that it will become invalid when the edit box is destroyed. The safest thing to do is make your own copy of the string using a function such as strcpy. Known bugs: None. See also: @{" GetEditBoxFloat " Link GetEditBoxFloat} @{" GetEditBoxInt " Link GetEditBoxInt} @{" MakeEditBox " Link MakeEditBox} @{" SetEditBoxText " Link SetEditBoxText} @endnode @node MakeEditBox "MakeEditBox function" Function prototype: EditBox *MakeEditBox(void *Parent, int x, int y, int len, int buflen, int BorderCol, int Bcol, int Tcol, int id, char *prestr, char *poststr, BOOL (*callfn) (EditBox*), long flags); Description: Creates a new edit box in the specified window or frame. Parameters: Parent: A pointer to an open GuiWindow or frame in which to create the editbox. x: The coordinate of the left edge of the new edit box relative to the left hand edge of the specified window/frame. y: The coordinate of the top edge of the new edit box relative to the top edge of the specified window/frame. Note that this is from the very top of a window so a y coordinate of 0 would cause the editbox to be at least partly obscured by the window's title bar if it had one. len: The length in pixels of the edit box. This length includes the border drawn around the edit box. buflen: The maximum number of characters that the user will be able to type into the new edit box. This number cannot be more than 256. BorderCol: The pen colour for the border. Bcol: The background pen colour for the edit box (ignored prior to Intuition version 37). Tcol: The pen colour for the text within the edit box as well as the pre-text and post-text (see the prestr and poststr parameters). id: This parameter can have any integral value. It won't affect the way the edit box behaves but it will get stored as part of the edit box structure and you can find out the value of any edit boxes id using the macro @{" GetEditBoxID " Link GetEditBoxID}. The main use for this is when creating arrays of edit boxes. For example, if you wanted the user to enter their address you might create an array of edit boxes like this: EditBox *ebAddress[5]; int l; for (l = 0; l < 5; l++) { ebAddress[l] = MakeEditBox(MyWin, 80, 80 + (10 * l), 244, 30, Col_EB1, Col_EB2, Col_EB3, l, NULL, NULL, AddrValidate, THREED | TEXT_EDIT); } Because l has been passed to MakeEditBox as the id for each address line, the five address lines will have different ids, ranging from 0 to 4. Now, let's say for example that you wanted to keep a record of the number of characters in each address line. You could define an array of integers like this: int numAddrChars[5]; And use your validation function (see the callfn parameter below) for the address line edit boxes to update your array like this: BOOL AddrValidate(EditBox *eb) { // Find out which address line has been changed. int index = GetEditBoxID(eb); // Update the character count numAddrChars[index] = strlen(GetEditBoxText(eb)); return TRUE; } Without the id parameter, you would have to check each edit box pointer of the array in turn against the pointer passed to the validation function which would be very innefficient. prestr: A NULL terminated text string containing text that you want to appear to the left of the edit box. Typically this would be some sort of the description giving the user an idea of what to type in the box. For example, if you were writing an address book application, you might have an edit box for the user to type a persons name into. This might have the prestr "Name :". Note that the parameter x supplies the left edge of the border around the editable part of the edit box. If you supply a prestr, that text will appear to the left of that box i.e. at a coordinate less than x so remember to leave room for your prestr when you set your x coordinate. If you do not want a prestr, set this to NULL. poststr: A NULL terminated text string containing text that you want to appear to the right of the text box. For example, if you wanted the user to enter their height in feet and inches you might use two edit boxes - the first with the prestr "Height:" and the poststr "feet" and the second with no prestr and the poststr "inches". If you do not want a poststr, set this to NULL. callfn: A pointer to a validation function for the edit box. This function will be called whenever the edit box loses focus (e.g. if the user has been typing in this box and then presses the tab key to activate the next edit box or clicks elsewhere in the window using the mouse). The function should have the following prototype: BOOL MyValidationFunction(EditBox *MyEditBox); When FoxGui activates your validation function it will pass a pointer to the edit box that triggered it so that you can use one validation function for more than one edit box (if you wish) and still determine which edit box has just been deactivated. In order to validate the data you will obviously need to know what the user has typed into your edit box and you can use one of the functions @{" GetEditBoxFloat " Link GetEditBoxFloat}, @{" GetEditBoxInt " Link GetEditBoxInt} or @{" GetEditBoxText " Link GetEditBoxText} to find this out. If you decide that what the user has typed is invalid, you may wish to tell the user so using the @{" GuiMessage " Link GuiMessage} function and you may want to force the user to correct it by re-activating the edit box (see below). Of course, your validation function can perform other action apart from validation. If the edit box was of type INT_EDIT or FLOAT_EDIT you may want to use the number they have entered for some form of calculation and display the result in an output box or another edit box. The function can really do whatever you want it to. Unlike other call-back functions, this one should return TRUE or FALSE. As mentioned above, if the user enters invalid data you might want to re-activate the edit box to force them to correct it. If your function returns FALSE then FoxGui will re-activate the edit box for you (overriding any calls made to the @{" SetEditBoxFocus " Link SetEditBoxFocus} function). If the data is valid or you don't want the edit box re-activated for any other reason then you should return TRUE. You should take great care when returning FALSE from this function - if the user has deactivated the edit box by clicking on another control then that control will not get activated unless this function returns TRUE. For example, if the user types invalid data into an edit box and then clicks on a tick box, the tick box will not change value and it's call-back function will not be activated unless the call-back function for the edit box returns TRUE. The only gadgets that the user will be able to activate under these conditions are gadgets in other applications, some system gadgets in the current application and scroll-bars. For example, the user could scroll a list box or resize the window while the edit box text was invalid but the focus would be returned to the edit box immediately afterwards. The function @{" SetEditBoxFocus " Link SetEditBoxFocus}, when called from within an edit boxes call-back function is not as clever. If you want to set the focus back to the edit box that just lost it then return FALSE, don't use SetEditBoxFocus. If you want to set the focus to a different edit box then use SetEditBoxFocus but do it as near to the end of the function as possible (calling GuiMessage, for example after a call to SetEditBoxFocus would completely ruin the effect of the call to SetEditBoxFocus becuase the window popping up will cause the edit box to lose focus again). If you are going to do anything that causes the focus to go anywhere other than where the user is expecting it to go it is polite to tell the user why (with a call to GuiMessage for example) otherwise you could completely confuse your user. flags: Currently, the following flags are available for edit boxes: THREED, TEXT_EDIT, INT_EDIT, FLOAT_EDIT, NO_EDIT, @{" S_AUTO_SIZE " Link S_AUTO_SIZE} and EB_CLEAR. Set the THREED flag if you want the border around the edit box to have a three dimensional look (it will appear slightly inset or pressed into the screen and will be drawn in the current FoxGui pens which can be modified by calling @{" SetGuiPens " Link SetGuiPens}). If you do not select the THREED flag then you will get a simple rectangle drawn around the editable area in the colour specified in the BorderCol parameter. EB_CLEAR specifies that the edit box will be clear (i.e. see-through). In other words, the background colour of the edit box will be the colour of the window or frame in which it was created. The other four flags are mutually exclusive. You can select at most one of the four but any of the four may be combined with the THREED and EB_CLEAR flags. All four _EDIT flags specify the filtering that will be applied to the edit box when the user types data into it. TEXT_EDIT allows the user to type absolutely any text into the edit box. INT_EDIT allows the user to enter integral numbers only. FLOAT_EDIT allows floating point or integral numbers to be entered (floating point numbers are those with a decimal point e.g. 3.14159). For FLOAT_EDIT edit boxes, the number of figures after the decimal point can be restricted using the function @{" SetEditBoxDP " Link SetEditBoxDP}. NO_EDIT prevents any text from being entered into the edit box at any time (whether the edit box is currently enabled or disabled) - I have no idea why you would want to use this. If you do not select any of the _EDIT flags then TEXT_EDIT is used by default. Returns: If successful a pointer to the new edit box is returned. NULL is returned if MakeEditBox fails. Known bugs: None. See also: @{" DestroyEditBox " Link DestroyEditBox} @{" DisableEditBox " Link DisableEditBox} @{" EnableEditBox " Link EnableEditBox} @{" GetEditBoxFloat " Link GetEditBoxFloat} @{" GetEditBoxInt " Link GetEditBoxInt} @{" GetEditBoxText " Link GetEditBoxText} @{" RefreshEditBox " Link RefreshEditBox} @{" RestoreEditBoxStatus " Link RestoreEditBoxStatus} @{" SetEditBoxCols " Link SetEditBoxCols} @{" SetEditBoxDP " Link SetEditBoxDP} @{" SetEditBoxFloat " Link SetEditBoxFloat} @{" SetEditBoxFocus " Link SetEditBoxFocus} @{" SetEditBoxInt " Link SetEditBoxInt} @{" SetEditBoxText " Link SetEditBoxText} @{" StoreEditBoxStatus " Link StoreEditBoxStatus} @endnode @node RefreshEditBox "RefreshEditBox function" Function prototype: void RefreshEditBox(EditBox *p); Description: Refresh the imagery of the specified edit box. You might want to do this if you have used a function such as @{" DisableAllEditBoxes " Link DisableAllEditBoxes} which has changed the state of one or more edit boxes without refreshing the imagery (all functions which change the state of an editbox can be instructed to refresh the imagery for you if you prefer). Parameters: p: A pointer to the edit box to be refreshed. Known bugs: None. See also: @{" DestroyAllEditBoxes " Link DestroyAllEditBoxes} @{" DestroyEditBox " Link DestroyEditBox} @{" DestroyWinEditBoxes " Link DestroyWinEditBoxes} @{" DisableAllEditBoxes " Link DisableAllEditBoxes} @{" DisableEditBox " Link DisableEditBox} @{" DisableWinEditBoxes " Link DisableWinEditBoxes} @{" EnableAllEditBoxes " Link EnableAllEditBoxes} @{" EnableEditBox " Link EnableEditBox} @{" EnableWinEditBoxes " Link EnableWinEditBoxes} @{" RestoreEditBoxStatus " Link RestoreEditBoxStatus} @endnode @node RestoreEditBoxStatus "RestoreEditBoxStatus function" Function prototype: void RestoreEditBoxStatus(BOOL redraw); Description: Restores the status of every edit box to the status it had when @{" StoreEditBoxStatus " Link StoreEditBoxStatus} was called. If StoreEditBoxStatus has never been called then RestoreEditBoxStatus will enable every edit box. Parameters: redraw: If TRUE, refresh the imagery of each edit box. Disabled edit boxes are shaded to show that input is not currently possible. Changing the status of edit boxes is faster if redraw is FALSE but this could be confusing because the edit box could then appear enabled when it is actually disabled or vice versa. You can refresh an edit box at any time by calling @{" RefreshEditBox " Link RefreshEditBox}. Known bugs: None. See also: @{" DisableAllEditBoxes " Link DisableAllEditBoxes} @{" DisableEditBox " Link DisableEditBox} @{" DisableWinEditBoxes " Link DisableWinEditBoxes} @{" EnableAllEditBoxes " Link EnableAllEditBoxes} @{" EnableEditBox " Link EnableEditBox} @{" EnableWinEditBoxes " Link EnableWinEditBoxes} @{" RefreshEditBox " Link RefreshEditBox} @{" StoreEditBoxStatus " Link StoreEditBoxStatus} @endnode @node SetEditBoxCols "SetEditBoxCols function" Function prototype: BOOL SetEditBoxCols(EditBox *p, int BorderCol, int Bcol, int Tcol); Description: Changes the colours of an edit box to the new ones specified and refreshes the edit box imagery. Parameters: p: A pointer to the edit box whose colours are to be changed. All other parameters are identical to the parameters to @{" MakeEditBox " Link MakeEditBox} of the same names. Returns: TRUE for success, FALSE for failure. Known bugs: None. See also: @{" MakeEditBox " Link MakeEditBox} @{" SetEditBoxDP " Link SetEditBoxDP} @{" SetEditBoxFocus " Link SetEditBoxFocus} @endnode @node SetEditBoxDP "SetEditBoxDP function" Function prototype: BOOL SetEditBoxDP(EditBox *p, int num); Description: Set (or change) the maximum number of figures that can be entered after the decimal point in an edit box of type FLOAT_EDIT. This function can be called at any point after the edit box is created so you should bear in mind that if the user has already had a chance to type text into the edit box then there may already be more digits after the decimal point than you want. Calling this function will not remove any extra digits that are already after the decimal point but this can be done by using @{" GetEditBoxFloat " Link GetEditBoxFloat} to get the current value in the edit box and then @{" SetEditBoxFloat " Link SetEditBoxFloat} which will truncate the number to the correct number of decimal places when setting the new value. For edit boxes of types other than FLOAT_EDIT, SetEditBoxDP won't prevent the user from typing more than the specified number of decimal places into the text box but it will affect the way @{" SetEditBoxFloat " Link SetEditBoxFloat} behaves when it is called for that edit box. Parameters: p: A pointer to the edit box to modify. num: The maximum number of digits to allow after the decimal point in the specified edit box. Returns: TRUE for success, FALSE for failure. Known bugs: None. See also: @{" GetEditBoxFloat " Link GetEditBoxFloat} @{" MakeEditBox " Link MakeEditBox} @{" SetEditBoxCols " Link SetEditBoxCols} @{" SetEditBoxFloat " Link SetEditBoxFloat} @{" SetEditBoxFocus " Link SetEditBoxFocus} @endnode @node SetEditBoxFloat "SetEditBoxFloat function" Function prototype: BOOL SetEditBoxFloat(EditBox *p, float num); Description: Set the text in the specified edit box to the number supplied. The number will be truncated to the maximum number of decimal places allowed in the edit box as set by the function @{" SetEditBoxDP " Link SetEditBoxDP}. This is true for all edit boxes, not just those of type FLOAT_EDIT. For example, the following code will cause the text in MyEditBox to be set to "3.14": float pi = 3.14159265; SetEditBoxDP(MyEditBox, 2); SetEditBoxFloat(MyEditBox, pi); Parameters: p: A pointer to the edit box whose text is to be changed. num: The floating point number whose value is to be converted to text, possibly truncated and placed in the edit box. Returns: TRUE for success, FALSE for failure. Known bugs: None. See also: @{" GetEditBoxFloat " Link GetEditBoxFloat} @{" MakeEditBox " Link MakeEditBox} @{" SetEditBoxCols " Link SetEditBoxCols} @{" SetEditBoxDP " Link SetEditBoxDP} @{" SetEditBoxFocus " Link SetEditBoxFocus} @{" SetEditBoxInt " Link SetEditBoxInt} @{" SetEditBoxText " Link SetEditBoxText} @endnode @node SetEditBoxFocus "SetEditBoxFocus function" Function prototype: BOOL SetEditBoxFocus(EditBox *p); Description: Attempts to activate the edit box specified. If successful, a cursor will appear in the edit box and the user will then be able to type data into it. Parameters: p: A pointer to the edit box to be activated. Returns: SetEditBoxFocus will return TRUE if Intuition claims to have successfully activated the edit box. Otherwise FALSE will be returned. Intuition might fail to activate the edit box if for example the user is holding the right mouse button down to display the menus. Known bugs: None. See also: Notes on the use of SetEditBoxFocus in edit box call-back functions (@{" MakeEditBox " Link MakeEditBox}). @{" DisableEditBox " Link DisableEditBox} @{" EnableEditBox " Link EnableEditBox} @{" RefreshEditBox " Link RefreshEditBox} @{" RestoreEditBoxStatus " Link RestoreEditBoxStatus} @{" StoreEditBoxStatus " Link StoreEditBoxStatus} @endnode @node SetEditBoxInt "SetEditBoxInt function" Function prototype: BOOL SetEditBoxInt(EditBox *p, int num); Description: Sets the edit box text to the number supplied. Parameters: p: A pointer to the edit box whose value is to be changed. num: The number to convert to text and place in the edit box. Returns: TRUE for success, FALSE for failure. Known bugs: None. See also: @{" GetEditBoxInt " Link GetEditBoxInt} @{" MakeEditBox " Link MakeEditBox} @{" SetEditBoxCols " Link SetEditBoxCols} @{" SetEditBoxFloat " Link SetEditBoxFloat} @{" SetEditBoxFocus " Link SetEditBoxFocus} @{" SetEditBoxText " Link SetEditBoxText} @endnode @node SetEditBoxText "SetEditBoxText function" Function prototype: BOOL SetEditBoxText(EditBox *p, char *text); Description: Set the text in the specified edit box to the string supplied. Parameters: p: A pointer to the edit box whose value is to be changed. text: A pointer to a text string to copy into the edit box. A copy will be made of the text string supplied so there is no need to preserve the string passed after calling the function. Returns: TRUE for success, FALSE for failure. Known bugs: None. See also: @{" GetEditBoxText " Link GetEditBoxText} @{" MakeEditBox " Link MakeEditBox} @{" SetEditBoxCols " Link SetEditBoxCols} @{" SetEditBoxFloat " Link SetEditBoxFloat} @{" SetEditBoxFocus " Link SetEditBoxFocus} @{" SetEditBoxInt " Link SetEditBoxInt} @endnode @node StoreEditBoxStatus "StoreEditBoxStatus function" Function prototype: void StoreEditBoxStatus(void); Description: Stores the status (enabled or disabled) of every FoxGui edit box in the application. You would typically do this if you wanted to temporarily disable all of the edit boxes and then at a later point return each edit box to it's previous state without having to know what the status of each edit box was and reset them individually. Your code might look like this: StoreEditBoxStatus(); DisableAllEditBoxes(TRUE); // Some code during which the user mustn't be able to edit any edit // boxes... // End of uninteruptable code. RestoreEditBoxStatus(TRUE); Known bugs: None. See also: @{" DisableAllEditBoxes " Link DisableAllEditBoxes} @{" DisableEditBox " Link DisableEditBox} @{" DisableWinEditBoxes " Link DisableWinEditBoxes} @{" EnableAllEditBoxes " Link EnableAllEditBoxes} @{" EnableEditBox " Link EnableEditBox} @{" EnableWinEditBoxes " Link EnableWinEditBoxes} @{" RefreshEditBox " Link RefreshEditBox} @{" RestoreEditBoxStatus " Link RestoreEditBoxStatus} @endnode @node GetEditBoxID "GetEditBoxID macro" Macro prototype: int GetEditBoxID(EditBox *p) Macro definition: #define GetEditBoxID(p) (p)->id Description: Returns the id of the specified edit box. For a full description of edit box ids, see @{" MakeEditBox " Link MakeEditBox}. Parameters: p: A pointer to the edit box whose id you want to know. Returns: The id of the edit box specified. See also: @{" Warnings on the use of macros " Link MacroWarnings} @{" MakeEditBox " Link MakeEditBox} @endnode @node ListBoxes "FoxGui Listbox functions" List boxes consist of a frame around a list of items. When a user clicks on an item in the list it becomes hilighted and (optionally) a function can be triggered. A function can also be triggered by a double-click if required. If there are more items in a list than can be shown in the frame, then the list box will automatically get a scroll bar (proportional gadget) on it's right hand edge which can be used to scroll up and down the list of items. If an item is added to the list box which is wider than the box itself, the list box will get a horizontal scroll bar (proportional gadget) on the bottom edge. Functions are supplied to sort the items in a list box (into numerical or alphabetical, ascending or descending order) and it is possible to have a list box arranged in columns by setting tab-stops. List boxes are drag-drop aware. Items can be dragged into or out of list boxes (see @{" Drag/Drop functionality " Link DragDropFunc}). The following listbox functions are currently available :- @{" AddListBoxItem " Link AddListBoxItem} @{" AddListBoxTitle " Link AddListBoxTitle} @{" ClearListBoxItems " Link ClearListBoxItems} @{" ClearListBoxTabStops " Link ClearListBoxTabStops} @{" ClearListBoxTitles " Link ClearListBoxTitles} @{" DestroyAllListBoxes " Link DestroyAllListBoxes} @{" DestroyListBox " Link DestroyListBox} @{" DestroyWinListBoxes " Link DestroyWinListBoxes} @{" DisableAllListBoxes " Link DisableAllListBoxes} @{" DisableListBox " Link DisableListBox} @{" DisableWinListBoxes " Link DisableWinListBoxes} @{" EnableAllListBoxes " Link EnableAllListBoxes} @{" EnableListBox " Link EnableListBox} @{" EnableWinListBoxes " Link EnableWinListBoxes} @{" HiElem " Link HiElem} @{" HiNum " Link HiNum} @{" HiText " Link HiText} @{" ListBoxRefresh " Link ListBoxRefresh} @{" MakeListBox " Link MakeListBox} @{" NoLines " Link NoLines} @{" NoTitles " Link NoTitles} @{" SetListBoxHiNum " Link SetListBoxHiNum} @{" SetListBoxTabStops " Link SetListBoxTabStops} @{" SetListBoxTopNum " Link SetListBoxTopNum} @{" SortListBox " Link SortListBox} @{" TopNum " Link TopNum} @endnode @node AddListBoxItem "AddListBoxItem function" Function prototype: ListBoxItem *AddListBoxItem(ListBox *nlb, char *item, BOOL refresh); Description: Adds a line of text to an existing FoxGui listbox. The item is added to the end of the list but the list can be sorted if you require it once all of the required items have been added. The items in a list box can contain tabs to align data in columns. Items in a list box are sometimes referred to in this manual as "elements". Parameters: nlb: The FoxGui list box to which to add the item. item: The text string to add to the list box. If the text string is too long to be shown in the list box then it will simply be truncated. If the text string contains tab characters (specified as '\t' in C) then each tab will cause the character following it to be printed at the next tab stop as specified when calling the function @{" SetListBoxTabStops " Link SetListBoxTabStops}. For a full example of using tabbed lists see the @{" SetListBoxTabStops " Link SetListBoxTabStops} function (which should be called before any elements are added). If you add more items than can fit within the list box then a scroll bar is automatically created at the right hand edge of the list box. refresh: If TRUE then the list box will be refreshed after this item has been added so that you see the item immediately (or you see the scrollbar resize if the item is outside the currently visible portion of the list box). If you are adding many items to a list box at once then it is quicker to add them all without refreshing and then do one refresh at the end - either by setting refresh to TRUE for the very last item added or by calling the function @{" ListBoxRefresh " Link ListBoxRefresh} after adding the last item. Returns: If successful, a pointer to the item which has been added, otherwise NULL. There is no good reason for maintaining a pointer to each item that you add because the listbox will do that for you but it may be important for your application to check this function for a non-NULL result just to check that it has succeeded. Known bugs: None. See also: @{" AddListBoxTitle " Link AddListBoxTitle} @{" ClearListBoxItems " Link ClearListBoxItems} @{" HiElem " Link HiElem} @{" HiNum " Link HiNum} @{" HiText " Link HiText} @{" ListBoxRefresh " Link ListBoxRefresh} @{" MakeListBox " Link MakeListBox} @{" NoLines " Link NoLines} @{" SetListBoxHiNum " Link SetListBoxHiNum} @{" SetListBoxTabStops " Link SetListBoxTabStops} @{" SetListBoxTopNum " Link SetListBoxTopNum} @{" SortListBox " Link SortListBox} @{" TopNum " Link TopNum} @endnode @node AddListBoxTitle "AddListBoxTitle function" Function prototype: BOOL AddListBoxTitle(ListBox *nlb, char *title, int frontpen, BOOL refresh); Description: Adds a title line to the specified list box. Unlike the items added to a list box, title lines cannot be sorted (they are always shown at the top of the list in the order that they were added) and are not scrolled by the scroll-bar (if present) on the right hand edge of the list box. When a list box is created, the Gui will calculate the maximum number of lines of text that can be shown in the list at a time (which will depend on the height of the list and the font size specified for the text) and will not allow the titles to fill the visible list space. In other words the Gui always allows room for at least one item to be shown in the list at a time. Any attempt to add a title to the last visible line of a list box will fail. In practice, title lines are usually far outnumbered by visible items if they are present at all. It is not necessary to have any titles on a list box if you prefer. As with list box items, if the list box has tab stops and the title specified has tab characters in it then the character immediately following each tab character will appear at the next tab stop set. In this way it is possible to have columns of text or data aligned with titles at the top. Parameters: nlb: A pointer to the FoxGui list box to which to add the title. title: The text string to add as a title to the specified list box. frontpen: The pen colour for the text to be drawn in. Items added to a list box all appear in the colour specified when the list box is created but titles can be given another colour in order to make them stand out. refresh: If TRUE then the list box will be refreshed after adding the title so that you see it immediately. If you want to add more than one title or a combination of titles and items at the same time then it is quicker not to refresh the list box after each but to wait until after adding the last one and then refresh the list box either by setting refresh to TRUE for the last title/item added or by calling @{" ListBoxRefresh " Link ListBoxRefresh} after adding it. Returns: TRUE for success, FALSE for failure. Known bugs: None. See also: @{" AddListBoxItem " Link AddListBoxItem} @{" ClearListBoxTitles " Link ClearListBoxTitles} @{" ListBoxRefresh " Link ListBoxRefresh} @{" MakeListBox " Link MakeListBox} @{" NoTitles " Link NoTitles} @{" SetListBoxTabStops " Link SetListBoxTabStops} @endnode @node ClearListBoxItems "ClearListBoxItems function" Function prototype: void ClearListBoxItems(ListBox *lb, BOOL refresh); Description: Removes all items from a FoxGui list box and frees all associated resources. This function does not clear the list boxes titles if any have been set. Parameters: lb: A pointer to the list box whose items are to be removed. refresh: If TRUE then the list box will be refreshed so that the user will see an empty list box. If you are emptying it to refill it again with different data then you may prefer to set refresh to FALSE and then refresh the list box after adding the new data. Known bugs: None. See also: @{" AddListBoxItem " Link AddListBoxItem} @{" ClearListBoxTabStops " Link ClearListBoxTabStops} @{" ClearListBoxTitles " Link ClearListBoxTitles} @{" DestroyListBox " Link DestroyListBox} @{" DisableListBox " Link DisableListBox} @{" ListBoxRefresh " Link ListBoxRefresh} @{" MakeListBox " Link MakeListBox} @{" NoLines " Link NoLines} @{" NoTitles " Link NoTitles} @endnode @node ClearListBoxTabStops "ClearListBoxTabStops function" Function prototype: void ClearListBoxTabStops(ListBox *nlb, BOOL refresh); Description: Clears any tab stops previously set for a list box. Parameters: nlb: A pointer to the list box whose tab stops are to be cleared. refresh: If TRUE the list box will be redrawn. The text for items in a list box is formatted at the time that the items are added to the list box - to do this every time the list box redraws is too slow. As a result, clearing the tab stops and refreshing the list will cause the existing items and titles in the list to be displayed exactly as though the tab stops still existed. Only titles and items added to the list box after calling this function will be affected. It is therefore unlikely that you will need to set refresh to TRUE when clearing the tab stops unless you have also made other changes to the list box which you haven't yet refreshed. Known bugs: None. See also: @{" AddListBoxItem " Link AddListBoxItem} @{" AddListBoxTitle " Link AddListBoxTitle} @{" ClearListBoxItems " Link ClearListBoxItems} @{" ClearListBoxTitles " Link ClearListBoxTitles} @{" DestroyListBox " Link DestroyListBox} @{" ListBoxRefresh " Link ListBoxRefresh} @{" MakeListBox " Link MakeListBox} @{" SetListBoxTabStops " Link SetListBoxTabStops} @endnode @node ClearListBoxTitles "ClearListBoxTitles function" Function prototype: void ClearListBoxTitles(ListBox *lb, BOOL refresh); Description: Removes all titles from a FoxGui list box and frees all associated resources. This function does not clear any items from the list box. Parameters: lb: A pointer to the list box whose titles are to be removed. refresh: If TRUE then the list box will be refreshed so that the user will see the list box without it's titles immediately. If you are removing them to replace them with alternative titles then you may prefer to set refresh to FALSE and then refresh the list box after adding the new titles. Known bugs: None. See also: @{" AddListBoxTitle " Link AddListBoxTitle} @{" ClearListBoxItems " Link ClearListBoxItems} @{" ClearListBoxTabStops " Link ClearListBoxTabStops} @{" ListBoxRefresh " Link ListBoxRefresh} @{" MakeListBox " Link MakeListBox} @{" NoTitles " Link NoTitles} @endnode @node DestroyAllListBoxes "DestroyAllListBoxes function" Function prototype: void DestroyAllListBoxes(BOOL refresh); Description: Destroy all FoxGui list boxes in the current application and free all associated resources. Parameters: refresh: If TRUE, refresh the windows containing the list boxes so that they are visibly removed. If you are going to close the windows anyway then refresh may as well be FALSE because this function is faster if refresh is FALSE. Known bugs: None. See also: @{" DestroyListBox " Link DestroyListBox} @{" DestroyWinListBoxes " Link DestroyWinListBoxes} @{" DisableListBox " Link DisableListBox} @{" ListBoxRefresh " Link ListBoxRefresh} @{" MakeListBox " Link MakeListBox} @endnode @node DestroyListBox "DestroyListBox function" Function prototype: BOOL DestroyListBox(ListBox *nlb, BOOL refresh); Description: Destroy the specified FoxGui list box. Parameters: nlb: A pointer to the FoxGui list box to be destroyed. refresh: If TRUE then the window which contains the list box will be resfreshed so that the list box disappears. If you are going to close the window anyway then set this to FALSE because the function is faster if you don't refresh the imagery. Returns: TRUE for success or FALSE for failure. Known bugs: None. See also: @{" Destroy " Link Destroy} @{" DestroyAllListBoxes " Link DestroyAllListBoxes} @{" DestroyWinListBoxes " Link DestroyWinListBoxes} @{" DisableListBox " Link DisableListBox} @{" ListBoxRefresh " Link ListBoxRefresh} @{" MakeListBox " Link MakeListBox} @endnode @node DestroyWinListBoxes "DestroyWinListBoxes function" Function prototype: void DestroyWinListBoxes(GuiWindow *w, BOOL refresh); Description: Destroy all FoxGui list boxes in the specified FoxGui window. Parameters: w: A pointer to an open FoxGui window containing list boxes to be destroyed. refresh: If TRUE, refresh the window so that the list boxes disappear. Set this to FALSE if you are about to close the window anyway because this function is faster if the window is not refreshed. Known bugs: None. See also: @{" DestroyAllListBoxes " Link DestroyAllListBoxes} @{" DestroyListBox " Link DestroyListBox} @{" DisableWinListBoxes " Link DisableWinListBoxes} @{" ListBoxRefresh " Link ListBoxRefresh} @{" MakeListBox " Link MakeListBox} @endnode @node DisableAllListBoxes "DisableAllListBoxes function" Function prototype: void DisableAllListBoxes(void); Description: Disable all FoxGui list boxes in the current application. Known bugs: None. See also: @{" DestroyAllListBoxes " Link DestroyAllListBoxes} @{" DisableListBox " Link DisableListBox} @{" DisableWinListBoxes " Link DisableWinListBoxes} @{" EnableAllListBoxes " Link EnableAllListBoxes} @{" ListBoxRefresh " Link ListBoxRefresh} @{" MakeListBox " Link MakeListBox} @endnode @node DisableListBox "DisableListBox function" Function prototype: BOOL DisableListBox(ListBox *lb); Description: Disable the specified FoxGui list box. Parameters: lb: A pointer to the list box to be disabled. Returns: TRUE for success, FALSE for failure. Known bugs: None. See also: @{" DestroyListBox " Link DestroyListBox} @{" DisableAllListBoxes " Link DisableAllListBoxes} @{" DisableControl " Link DisableControl} @{" DisableWinListBoxes " Link DisableWinListBoxes} @{" EnableListBox " Link EnableListBox} @{" ListBoxRefresh " Link ListBoxRefresh} @{" MakeListBox " Link MakeListBox} @endnode @node DisableWinListBoxes "DisableWinListBoxes function" Function prototype: void DisableWinListBoxes(GuiWindow *w); Description: Disable all FoxGui list boxes in the specified FoxGui window. Parameters: w: A pointer to an open FoxGui window whose list boxes are to be disabled. Known bugs: None. See also: @{" DestroyWinListBoxes " Link DestroyWinListBoxes} @{" DisableAllListBoxes " Link DisableAllListBoxes} @{" DisableListBox " Link DisableListBox} @{" EnableWinListBoxes " Link EnableWinListBoxes} @{" ListBoxRefresh " Link ListBoxRefresh} @{" MakeListBox " Link MakeListBox} @endnode @node EnableAllListBoxes "EnableAllListBoxes function" Function prototype: void EnableAllListBoxes(void); Description: Enable all FoxGui list boxes in the current application. Known bugs: None. See also: @{" DisableAllListBoxes " Link DisableAllListBoxes} @{" EnableListBox " Link EnableListBox} @{" EnableWinListBoxes " Link EnableWinListBoxes} @{" MakeListBox " Link MakeListBox} @endnode @node EnableListBox "EnableListBox function" Function prototype: BOOL EnableListBox(ListBox *lb); Description: Enable the specified disabled FoxGui list box. When created, list boxes are initially enabled. Parameters: lb: A pointer to a disabled FoxGui list box. Returns: TRUE for success, FALSE for failure. Known bugs: None. See also: @{" DisableListBox " Link DisableListBox} @{" EnableAllListBoxes " Link EnableAllListBoxes} @{" EnableControl " Link EnableControl} @{" EnableWinListBoxes " Link EnableWinListBoxes} @{" MakeListBox " Link MakeListBox} @endnode @node EnableWinListBoxes "EnableWinListBoxes function" Function prototype: void EnableWinListBoxes(GuiWindow *w); Description: Enable all disabled FoxGui list boxes in the specified FoxGui window. Parameters: w: A pointer to a GuiWindow. Known bugs: None. See also: @{" DisableWinListBoxes " Link DisableWinListBoxes} @{" EnableAllListBoxes " Link EnableAllListBoxes} @{" EnableListBox " Link EnableListBox} @{" MakeListBox " Link MakeListBox} @endnode @node HiElem "HiElem function" Function prototype: ListBoxItem *HiElem(ListBox *lb); Description: This function returns a pointer to the currently hilighted item in the specified FoxGui list box. If there is no hilighted item or the function fails for any other reason then NULL is returned. This function is unlikely to be useful for your FoxGui applications. The functions @{" HiNum " Link HiNum} and @{" HiText " Link HiText} are likely to be more useful. Parameters: lb: A pointer to a FoxGui list box. Returns: A pointer to the currently hilighted element. Note that if the list box has tab stops set and the hilighted element contains tabs then the line of the list box will consist of more than one element and the pointer returned is the pointer to the first of these. Known bugs: None. See also: @{" AddListBoxItem " Link AddListBoxItem} @{" ClearListBoxItems " Link ClearListBoxItems} @{" ClearListBoxTabStops " Link ClearListBoxTabStops} @{" HiNum " Link HiNum} @{" HiText " Link HiText} @{" MakeListBox " Link MakeListBox} @{" SetListBoxHiNum " Link SetListBoxHiNum} @{" SetListBoxTabStops " Link SetListBoxTabStops} @{" TopNum " Link TopNum} @endnode @node HiNum "HiNum function" Function prototype: int HiNum(ListBox *lb); Description: Returns the number of the currently hilighted item in a FoxGui list box. If there is no currently hilighted item or if any other error occurs, 0 is returned (list box items are numbered starting at 1 not 0). Parameters: lb: A pointer to a FoxGui list box. Returns: The number of the hilighted item. Known bugs: None. See also: @{" AddListBoxItem " Link AddListBoxItem} @{" ClearListBoxItems " Link ClearListBoxItems} @{" HiElem " Link HiElem} @{" HiText " Link HiText} @{" MakeListBox " Link MakeListBox} @{" NoLines " Link NoLines} @{" NoTitles " Link NoTitles} @{" SetListBoxHiNum " Link SetListBoxHiNum} @{" SetListBoxTopNum " Link SetListBoxTopNum} @{" TopNum " Link TopNum} @endnode @node HiText "HiText function" Function prototype: char *HiText(ListBox *lb); Description: Returns a pointer to a text string containing the text of the currently hilighted item in the list box. Parameters: lb: A pointer to a FoxGui list box. Returns: The text of the hilighted item in the list box. Note that this is a pointer to the text actually used by the list box itself so if you want to compare this or output it directly in some way then that's fine but if you need to modify it at all then you should take a copy using strcpy() or similar. Note also that if the list box has tab stops and the hilighted entry contains tabs then the text returned is only the text for the first column (i.e. up to the first tab stop). It isn't currently possible to directly retrieve text for the subsequent columns of a tabbed list box. Known bugs: None. See also: @{" HiElem " Link HiElem} @{" HiNum " Link HiNum} @{" MakeListBox " Link MakeListBox} @{" SetListBoxHiNum " Link SetListBoxHiNum} @endnode @node ListBoxRefresh "ListBoxRefresh function" Function prototype: void ListBoxRefresh(ListBox *lb); Description: Refreshes a list box. Most list box functions that change a list box in any way take a boolean parameter that specifies whether or not to refresh the list box afterwards. This is so that you can make multiple changes (e.g. add loads of items) without refreshing and then just refresh once at the end (which is faster than doing a refresh for each change). Parameters: lb: A pointer to the FoxGui list box to refresh. Known bugs: None. See also: @{" AddListBoxItem " Link AddListBoxItem} @{" AddListBoxTitle " Link AddListBoxTitle} @{" ClearListBoxItems " Link ClearListBoxItems} @{" ClearListBoxTabStops " Link ClearListBoxTabStops} @{" ClearListBoxTitles " Link ClearListBoxTitles} @{" DestroyAllListBoxes " Link DestroyAllListBoxes} @{" DestroyListBox " Link DestroyListBox} @{" DestroyWinListBoxes " Link DestroyWinListBoxes} @{" MakeListBox " Link MakeListBox} @{" SetListBoxHiNum " Link SetListBoxHiNum} @{" SetListBoxTabStops " Link SetListBoxTabStops} @{" SetListBoxTopNum " Link SetListBoxTopNum} @{" SortListBox " Link SortListBox} @endnode @node MakeListBox "MakeListBox function" Function prototype: ListBox *MakeListBox(void *Parent, int left, int top, int width, int height, int lborder, int tborder, int frontpen, struct TextAttr *font, int (*selfn) (ListBox*), int flags, ...) Description: Make a new FoxGui list box. Parameters: Parent: A pointer to an open FoxGui window or frame in which to create the new list box. left: The x coordinate of the left edge of the list box relative to the left edge of the window/frame. top: The y coordinate of the top edge of the list box relative to the top edge of the window/frame. width: The width of the list box in pixels. Note that this includes the width of the scroll gadget on the right hand edge when there is one. height: The height of the list box in pixels. lborder: Left border - the distance in pixels between the left border of the list box and the left edge of the text for the titles and items within it. 2 or 3 pixels is usually sufficient to make it look neat. tborder: Top border - the distance in pixels between the top border of the list box and the top edge of the text for the first title/item in the list box. 1 or 2 pixels is usually sufficient to make it look neat. frontpen: The pen colour used for all items added to the list box and the arrows drawn on the scroll buttons. font: A pointer to an Intuition TextAttr structure containing a font to use for all items and titles in the list box. If you want to use the default FoxGui font then you can just pass NULL. selfn: A pointer to a function to be called when an item in the list box is clicked on by the user. Note that this function won't be called if the hilighted item is changed by scrolling the list box or by using the up & down cursor keys to scroll through the items - only if the user actually clicks on an item with the mouse. The function should have the following prototype :- int MyListBoxSelFn(ListBox *lb) and should (like most other FoxGui call-back functions) return either @{" GUI_END " Link GuiContinueEnd} or @{" GUI_CONTINUE " Link GuiContinueEnd}. The function is passed a pointer to the list box from which an item was selected (so that you can use the same selection function for more than one list box if you wish) but is not passed any indication of which item was selected. However, since the selected item will now be hilighted you can find out which item was selcted using @{" HiElem " Link HiElem}, @{" HiNum " Link HiNum}, or @{" HiText " Link HiText}. flags: The following flags are currently available for list boxes: LB_DBLCLICK, LB_DRAG, LB_DRAGIMAGE, LB_DROP and @{" S_AUTO_SIZE " Link S_AUTO_SIZE}. The LB_DRAG flag should be specified if you want the user to be able to drag data out of this list box into other drag/drop aware controls. If you wish to supply your own mouse pointer for use during drag/drop actions then specify the LB_DRAGIMAGE flag. If you want to be able to drop data dragged from other drag/drop aware controls into this list box then specify the LB_DROP flag. If you want to specify an action to occur when a user double clicks on an item in the list box then specify the LB_DBLCLICK flag. If you specify any of these flags then you will need to pass one or more extra parameters to the MakeListBox function. These are described below. Extra Parameters: int (*Eventfn) (struct ListBoxStruct *lb, short Event, int ItemNum, void **DataPtr): A pointer to a function to handle all events other than selection which is handled by selfn described above. This parameter should be specified if any of the following flags have been specified: LB_DBLCLICK, LB_DRAG or LB_DROP. The function will be called whenever one of those events occurs and will be passed a pointer to the list box (so that your function can be used to handle events for more than one list box). The Event parameter will be one of LB_DBLCLICK, LB_DRAG or LB_DROP depending on which event occured and ItemNum will contain the item number of the item that was double clicked on or dragged out of the box or, in the case of the LB_DROP event, the item number of the item above which the cursor was positioned when the user let go of the mouse button. In the case of the LB_DROP event, ItemNum will be zero if the drop occurred in an area where there was no item (for example if the drop occurred over one of the list boxes titles). If data has been dragged from another drag/drop aware control and dropped in this one then *DataPtr will be a pointer to the data that was dragged which would have been set in the event function for the originating control. If data is being dragged from this control into another drag/drop aware control (the LB_DRAG event) then you can set *DragData to point to anything you want and if the drop event occurs above another drag/drop aware control, that pointer will be passed to the event function of that control. As with almost all user-defined functions called directly by FoxGui, this function should return either @{" GUI_CONTINUE " Link GuiContinueEnd} or @{" GUI_END " Link GuiContinueEnd} but you should see the notes in the @{" Drag/Drop functionality " Link DragDropFunc} section about return values from drag event functions. unsigned short *DragPointer: A pointer to an array of numbers making up a standard Intuition sprite data structure. This must be stored in chip memory since it is to be used as a mouse pointer. This parameter should only be specified if the LB_DRAGIMAGE flag is set. int Width: The width in pixels of the pointer provided. The maximum width of an Amiga mouse pointer is 16 pixels. This parameter should only be specified if the LB_DRAGIMAGE flag is set. int Height: The height in pixels of the pointer provided. There is no maximum height. This parameter should only be specified if the LB_DRAGIMAGE flag is set. int XOffset: int YOffset: These two numbers specify the offset of the pointers hot-spot from the top left corner of the sprite. They are typically zero or negative. These parameters should only be specified if the LB_DRAGIMAGE flag is set. Returns: If successful, a pointer to a new FoxGui list box. NULL otherwise. Known bugs: None. See also: @{" Drag/Dropp functionality " Link DragDropFunc} @{" AddListBoxItem " Link AddListBoxItem} @{" AddListBoxTitle " Link AddListBoxTitle} @{" ClearListBoxItems " Link ClearListBoxItems} @{" ClearListBoxTabStops " Link ClearListBoxTabStops} @{" ClearListBoxTitles " Link ClearListBoxTitles} @{" DestroyAllListBoxes " Link DestroyAllListBoxes} @{" DestroyListBox " Link DestroyListBox} @{" DestroyWinListBoxes " Link DestroyWinListBoxes} @{" DisableAllListBoxes " Link DisableAllListBoxes} @{" DisableListBox " Link DisableListBox} @{" DisableWinListBoxes " Link DisableWinListBoxes} @{" EnableAllListBoxes " Link EnableAllListBoxes} @{" EnableListBox " Link EnableListBox} @{" EnableWinListBoxes " Link EnableWinListBoxes} @{" HiElem " Link HiElem} @{" HiNum " Link HiNum} @{" HiText " Link HiText} @{" ListBoxRefresh " Link ListBoxRefresh} @{" NoLines " Link NoLines} @{" NoTitles " Link NoTitles} @{" SetListBoxHiNum " Link SetListBoxHiNum} @{" SetListBoxTabStops " Link SetListBoxTabStops} @{" SetListBoxTopNum " Link SetListBoxTopNum} @{" SortListBox " Link SortListBox} @{" TopNum " Link TopNum} @endnode @node NoLines "NoLines function" Function prototype: int NoLines(ListBox *lb); Description: Uses the list boxes height, top border and font size to calculate the number of lines of text that can be shown in the visible area of a list box. (Obviously this does not determine the maximum number of items that can be added to a list box because the visible portion of a list box can be scrolled but it does limit the number of titles that the list box can have because the list box must be able to show at least one item at all times. e.g. if NoLines returns 10 then you wouldn't be able to add more than 9 titles). Parameters: lb: A pointer to a FoxGui list box. Returns: The number of lines of text that can be displayed in the list box. Known bugs: None. See also: @{" MakeListBox " Link MakeListBox} @{" NoTitles " Link NoTitles} @endnode @node NoTitles "NoTitles function" Function prototype: int NoTitles(ListBox *lb); Description: Returns the number of titles currently displayed in the specified list box. Parameters: lb: A pointer to a FoxGui list box. Returns: The number of titles currently displayed in the specified list box. Known bugs: None. See also: @{" AddListBoxTitle " Link AddListBoxTitle} @{" ClearListBoxTitles " Link ClearListBoxTitles} @{" MakeListBox " Link MakeListBox} @{" NoLines " Link NoLines} @endnode @node SetListBoxHiNum "SetListBoxHiNum function" Function prototype: void SetListBoxHiNum(ListBox *lb, int num, BOOL refresh); Description: Hilight the specified item number in the specified list box. This function will fail if you specify a number greater than the number of items in the list box. Note that if the item number specified is not currently in the visible portion of the list box, the list box will not be automatically scrolled to show the hilighted item. You can do this yourself using the function @{" SetListBoxTopNum " Link SetListBoxTopNum}. You can use a combination of other list box functions to work out whether or not your target item number is currently in the visible portion of the list box as follows :- if (itemnum >= TopNum(lb) && itemnum <= NoLines(lb) - NoTitles(lb) + TopNum(lb) - 1) { // itemnum is in the visible portion of list box lb. } Parameters: lb: A pointer to a FoxGui list box. num: The item number of the item to hilight. refresh: If TRUE, refresh the list box to unhilight the previously selected item and hilight the selected item. Otherwise, leave the list box looking as it was. Typically you would set this to FALSE if you had many other changes to make to the list box - it's quicker to make all of the changes without refreshing and then refresh the list box just once at the end. Known bugs: None. See also: @{" AddListBoxItem " Link AddListBoxItem} @{" HiElem " Link HiElem} @{" HiNum " Link HiNum} @{" HiText " Link HiText} @{" ListBoxRefresh " Link ListBoxRefresh} @{" MakeListBox " Link MakeListBox} @{" NoLines " Link NoLines} @{" NoTitles " Link NoTitles} @{" SetListBoxTopNum " Link SetListBoxTopNum} @{" TopNum " Link TopNum} @endnode @node SetListBoxTabStops "SetListBoxTabStops function" Function prototype: BOOL SetListBoxTabStops(ListBox *nlb, BOOL refresh, short num, ...); Description: Set the tab stops in a list box so that data can be displayed in columns. If you want a tabbed list box, you should always set your tab stops before adding any titles or items to the list. Calling SetListBoxTabStops after items have been added to the list won't affect items that were added prior to the SetListBoxTabStops call, only those that are added subsequently. Parameters: nlb: A pointer to a FoxGui list box. refresh: If TRUE, refresh the list box after setting the tab stops. Since SetListBoxTabStops doesn't currently afffect items and titles that have already been added, there's currently no real reason to set this to TRUE. num: The number of tab stops to set. Note that no tab stop is necessary for the first column which will always be at the left border of the list box. In other words, if you want to have text in 3 columns, you only need to set 2 tab stops - for the second and third columns. ...: The remaining parameters should be of type int and there should be num of them. Each should be the offset for that tab stop in pixels from the left border. For example, if you have a list box lb in which you want to show three columns of text entitled "Stock no.", "Description" and "In stock", you might set your tab stops and titles as follows: /* Our list box uses an 8 point fixed width font so to allow room for a 9 digit stock no. preeceded by a two character width gap between columns, we'll put the first tab stop at 11*8 and then to allow room for a 17 character description with the same gap between columns we'll put the second tab stop at 30*8. */ SetListBoxTabStops(lb, FALSE, 2, 11*8, 30*8); AddListBoxTitle(lb, "Stock no.\tDescription\tIn stock"); Returns: TRUE for success, FALSE for failure. Known bugs: None. See also: @{" AddListBoxItem " Link AddListBoxItem} @{" AddListBoxTitle " Link AddListBoxTitle} @{" ClearListBoxItems " Link ClearListBoxItems} @{" ClearListBoxTabStops " Link ClearListBoxTabStops} @{" ClearListBoxTitles " Link ClearListBoxTitles} @{" ListBoxRefresh " Link ListBoxRefresh} @{" MakeListBox " Link MakeListBox} @endnode @node SetListBoxTopNum "SetListBoxTopNum function" Function prototype: void SetListBoxTopNum(ListBox *lb, int num, BOOL refresh); Description: Sets the top item number shown in a list box. The user of your application can do this themselves using the scroll bar or buttons on the right hand edge of the list box but this function allows you to set it from within your application code if you require. If a user scrolls the list using the scroll bar or buttons, the Gui will always attempt to keep the list box full e.g. if the list box has 20 lines, 100 elements and 1 line of titles then the list box can show 19 elements at a time (20 lines - 1 title = 19 elements) and so the user won't be allowed to scroll down below the point where the top element shown is item number 82 (82 to 100 inclusive is 19 items). This function provides no such checking for you and would quite happily set the top item number to 101! However, it is advised that you try to keep to the look and feel of the Gui by not doing so and you can use the functions @{" NoLines " Link NoLines} and @{" NoTitles " Link NoTitles} to help you work out the highest number that you should specify for the top number in the list box. You will have to keep a count of the number of items in the list box yourself. Parameters: lb: A pointer to a FoxGui list box. num: The item number to set as the top item in the list box. refresh: If TRUE, refresh the list box to show the list starting with the new top item. Set this to FALSE if you have many other changes to make to the list box - that way, instead of refreshing after each change you can refresh just once at the end. Known bugs: None. See also: @{" ListBoxRefresh " Link ListBoxRefresh} @{" MakeListBox " Link MakeListBox} @{" NoLines " Link NoLines} @{" NoTitles " Link NoTitles} @{" SetListBoxHiNum " Link SetListBoxHiNum} @{" TopNum " Link TopNum} @endnode @node SortListBox "SortListBox function" Function prototype: void SortListBox(ListBox *p, int flags, int startnum, BOOL refresh); Description: Sorts the items in a list box (numerically or alphabetically) into ascending or descending order. Parameters: p: A pointer to a list box to sort. flags: This should be one of ASCENDING or DESCENDING (to sort alphabetically), NUM_ASCENDING or NUM_DESCENDING to sort numerically. If none of these are specified then DESCENDING is assumed. When sorting numerically, the function attempts to turn the text for each item into a number and sorts using those numbers - any items which can't be turned into numbers are treated as if they contained the number zero. startnum: The item number to start sorting at. To sort the whole list, set this to 1. Setting this to any number (n) greater than 1 will cause the first n-1 items to remain exactly where they are and the items from n onwards to be sorted. refresh: If TRUE, refresh the list to show the items in their new order. Set this to FALSE if you want to make other changes before refreshing the list (it's faster to do all of your changes and then refresh once than to refresh after each change). Known bugs: None. See also: @{" AddListBoxItem " Link AddListBoxItem} @{" ClearListBoxItems " Link ClearListBoxItems} @{" ListBoxRefresh " Link ListBoxRefresh} @{" MakeListBox " Link MakeListBox} @endnode @node TopNum "TopNum function" Function prototype: int TopNum(ListBox *lb); Description: Returns the item number of the first item currently displayed in the visible portion of a list box. Parameters: lb: A pointer to a FoxGui list box. Returns: The number of the item cureently at the top of the visible portion of the list box. Known bugs: None. See also: @{" HiElem " Link HiElem} @{" HiNum " Link HiNum} @{" HiText " Link HiText} @{" MakeListBox " Link MakeListBox} @{" NoLines " Link NoLines} @{" NoTitles " Link NoTitles} @endnode @node DDListBoxes "FoxGui Drop-Down Listbox functions" Drop-down list boxes are likely to be less familier to Amiga users than many of the other controls in FoxGui. Most Amiga applications don't use them but if you have used MUI applications or Windows applications on a PC then you will recognise them instantly. Drop-down list boxes are like a cross between edit boxes and list boxes. When you see a drop-down list box in an application window, what you will see is an edit box with a button attached to it's right hand end. You cannot edit the contents of the edit box directly but if you click on the button, a list of options (which looks exactly like a list box) appears below the edit box. The list can be scrolled (if it contains more items than can be shown at once) exactly as a list box can but clicking on an item causes that item to be copied into the edit box and the list to disappear. In this way a user can choose from a set of options decided by the programmer. On Amigas running OS 2.0 or greater, the user can tab (and shift tab) to drop-down list boxes exactly as with edit boxes. When the user has selected the drop-down list box (either by tabbing or by clicking in the edit box part with the mouse) the user can select items in the list by using short-cut keys. For example, if the list box is selected and the user presses the "t" key, the first item in the list beginning with the letter t is selected. If no item in the list begins with the letter t then nothing is selected. If more than one item begins with a t then pressing t repeatedly will cycle between them. As with tabbing, short-cut keys are only supported on OS version 2.0 and above. The following drop-down listbox functions are currently available :- @{" AddToDDListBox " Link AddToDDListBox} @{" AssociateDDListBox " Link AssociateDDListBox} @{" ClearDDListBox " Link ClearDDListBox} @{" DestroyAllDDListBoxes " Link DestroyAllDDListBoxes} @{" DestroyDDListBox " Link DestroyDDListBox} @{" DestroyWinDDListBoxes " Link DestroyWinDDListBoxes} @{" DisableAllDDListBoxes " Link DisableAllDDListBoxes} @{" DisableDDListBox " Link DisableDDListBox} @{" DisableWinDDListBoxes " Link DisableWinDDListBoxes} @{" EnableAllDDListBoxes " Link EnableAllDDListBoxes} @{" EnableDDListBox " Link EnableDDListBox} @{" EnableWinDDListBoxes " Link EnableWinDDListBoxes} @{" MakeDDListBox " Link MakeDDListBox} @{" MakeSubDDListBox " Link MakeSubDDListBox} @{" RemoveFromDDListBox " Link RemoveFromDDListBox} @{" RestoreDDListBoxStatus " Link RestoreDDListBoxStatus} @{" SetDDListBoxPopup " Link SetDDListBoxPopup} @{" SortDDListBox " Link SortDDListBox} @{" StoreDDListBoxStatus " Link StoreDDListBoxStatus} The following drop-down listbox operations are defined as macros :- @{" GetDDListBoxID " Link GetDDListBoxID} @{" GetDDListBoxText " Link GetDDListBoxText} @{" SetDDListBoxText " Link SetDDListBoxText} @endnode @node AddToDDListBox "AddToDDListBox function" Function prototype: BOOL AddToDDListBox(DDListBox *list, char *str); Description: Adds an item (a line of text) to a drop-down list box. The items in a drop-down list box don't become visible until the user clicks on the button at the right hand end of the drop-down list box (on OS V37 or above this can also be achieved by clicking in or tabbing to the text part of the drop-down list box and then pressing the space bar). Parameters: list: A pointer to a FoxGui drop-down list box as returned by the @{" MakeDDListBox " Link MakeDDListBox} function. str: A pointer to a NULL terminated text string to add as the next item in the list. The items in a drop-down list box can be sorted into order using the function @{" SortDDListBox " Link SortDDListBox}. Returns: TRUE if successful, FALSE otherwise. Known bugs: None. See also: @{" AssociateDDListBox " Link AssociateDDListBox} @{" ClearDDListBox " Link ClearDDListBox} @{" MakeDDListBox " Link MakeDDListBox} @{" MakeSubDDListBox " Link MakeSubDDListBox} @{" RemoveFromDDListBox " Link RemoveFromDDListBox} @{" SortDDListBox " Link SortDDListBox} @endnode @node AssociateDDListBox "AssociateDDListBox function" Function prototype: BOOL AssociateDDListBox(DDListBox *l, DDListBox *m); Description: Describing what this function does would be very tricky without an example so here comes an example: Let's assume that you have twenty items that you want a user to be able to choose from but you want the user to be able to choose up to five of those items simultaneously. A list box or a drop-down list box only allow you to choose one item at a time so you need another solution. One solution (probably not the most elegant but the one that illustrates the use of this function) is to create five drop-down list boxes, each populated with the same list of items so that the user can choose an item in each. It would be very wasteful to have to populate each drop-down list box with the same set of items which is where this function comes in. AssociateDDListBox causes two drop-down list boxes to become associated with each other. What this means is that they share a list of items. Adding an item to one will then also cause it to be added to the other. Removing an item from one will also cause it to be removed from the other. This is not achieved by automating the process of adding to the other list box - they physically share the same list data which means that you save the extra memory that would otherwise be needed. You can associate as many list boxes together as you like - there is no limit. However, please read the known bugs section at the end of this function definition. Parameters: l: A pointer to the destination drop-down list box. This list box must be empty (i.e. have no items in it) for this function to succeed. If the list box already has items in it, you can clear them using the @{" ClearDDListBox " Link ClearDDListBox} function. m: A pointer to the source drop-down list box. It is recommended that you fully populate this list box before making the association but it is only @{i}necessary @{ui}to make sure that it contains one item before the association is made. Returns: TRUE for success, FALSE for failure. Known bugs: If your source drop-down list box is empty then all sorts of problems could occur. AssociateDDListBox will return TRUE but the list boxes won't quite behave as though they are associated. At some point I will fix the code to stop this from happening but for the time being it should be fairly simple just to ensure that you add at least one item to your source drop-down list before making the association. Clearing a list box which is associated with others is also a problem - not for the source box itself but for any drop-down list boxes associated with it. Please believe that if the solution to this problem were trivial I would have done it a long time ago but it would be a lot of hard work for what's probably going to be a rarely used function so my priorities lie elsewhere. If you really need this sorting out then hassle me. See also: @{" AddToDDListBox " Link AddToDDListBox} @{" ClearDDListBox " Link ClearDDListBox} @{" MakeDDListBox " Link MakeDDListBox} @{" MakeSubDDListBox " Link MakeSubDDListBox} @{" RemoveFromDDListBox " Link RemoveFromDDListBox} @endnode @node ClearDDListBox "ClearDDListBox function" Function prototype: void ClearDDListBox(DDListBox *l); Description: Removes all of the items from the specified drop-down list box. Parameters: l: A pointer to a FoxGui drop-down list box. Known bugs: This function can cause problems with associated drop-down list boxes. See the @{" AssociateDDListBox " Link AssociateDDListBox} function for more details. See also: @{" AddToDDListBox " Link AddToDDListBox} @{" AssociateDDListBox " Link AssociateDDListBox} @{" MakeDDListBox " Link MakeDDListBox} @{" MakeSubDDListBox " Link MakeSubDDListBox} @{" RemoveFromDDListBox " Link RemoveFromDDListBox} @endnode @node DestroyAllDDListBoxes "DestroyAllDDListBoxes function" Function prototype: void DestroyAllDDListBoxes(BOOL refresh); Description: Destroys all drop-down list boxes in the current application. Parameters: refresh: If TRUE, refresh the windows containing the drop-down list boxes so that they visibly disappear. If you're about to close all of the windows anyway then there's no point - set this to FALSE. Known bugs: None. See also: @{" DestroyDDListBox " Link DestroyDDListBox} @{" DestroyWinDDListBoxes " Link DestroyWinDDListBoxes} @{" MakeDDListBox " Link MakeDDListBox} @{" MakeSubDDListBox " Link MakeSubDDListBox} @endnode @node DestroyDDListBox "DestroyDDListBox function" Function prototype: void DestroyDDListBox(DDListBox *p, BOOL refresh); Description: Destroy the specified FoxGui drop-down list box. Parameters: p: A pointer to the drop-down list box to destroy. refresh: If TRUE, refresh the window containing the drop-down list box so that it visibly disappears. If you're about to close the window anyway then there's no point - set this to FALSE. Known bugs: None. See also: @{" Destroy " Link Destroy} @{" DestroyAllDDListBoxes " Link DestroyAllDDListBoxes} @{" DestroyWinDDListBoxes " Link DestroyWinDDListBoxes} @{" MakeDDListBox " Link MakeDDListBox} @{" MakeSubDDListBox " Link MakeSubDDListBox} @endnode @node DestroyWinDDListBoxes "DestroyWinDDListBoxes function" Function prototype: void DestroyWinDDListBoxes(GuiWindow *c, BOOL refresh); Description: Destroy all of the drop-down list boxes in the specified window. Parameters: c: A pointer to the FoxGui window whose drop-down list boxes are to be destroyed refresh: If TRUE, refresh the window so that the drop-down list boxes visibly disappear. However, if you're about to close the window anyway then don't bother refreshing it - set this to FALSE. Known bugs: None. See also: @{" DestroyAllDDListBoxes " Link DestroyAllDDListBoxes} @{" DestroyDDListBox " Link DestroyDDListBox} @{" MakeDDListBox " Link MakeDDListBox} @{" MakeSubDDListBox " Link MakeSubDDListBox} @endnode @node DisableAllDDListBoxes "DisableAllDDListBoxes function" Function prototype: void DisableAllDDListBoxes(BOOL redraw); Description: Disable all of the drop-down list boxes in the current application. See @{" DisableDDListBox " Link DisableDDListBox} for exact details about what this entails. Parameters: redraw: If TRUE, redraw the drop-down list boxes so that they appear disabled. Known bugs: None. See also: @{" DisableDDListBox " Link DisableDDListBox} @{" DisableWinDDListBoxes " Link DisableWinDDListBoxes} @{" EnableAllDDListBoxes " Link EnableAllDDListBoxes} @{" MakeDDListBox " Link MakeDDListBox} @{" MakeSubDDListBox " Link MakeSubDDListBox} @{" RestoreDDListBoxStatus " Link RestoreDDListBoxStatus} @{" StoreDDListBoxStatus " Link StoreDDListBoxStatus} @endnode @node DisableDDListBox "DisableDDListBox function" Function prototype: void DisableDDListBox(DDListBox *p, BOOL redraw); Description: Disable the specified FoxGui drop-down list box. When a drop-down list box is disabled, clicking on the button at it's right hand end has no effect. Also, under OS37 and above where it is possible to tab between edit boxes and drop-down list boxes, disabled drop-down list boxes will be excluded from the tab cycle and it will also be impossible to activate them by clicking in the text part. Parameters: p: A pointer to the drop-down list box to disable. redraw: If TRUE then the drop-down list box will be redrawn to appear disabled. When a drop-down list box is disabled, the text part appears shaded to imply that it's impossible to change the text in it. Known bugs: None. See also: @{" DisableAllDDListBoxes " Link DisableAllDDListBoxes} @{" DisableControl " Link DisableControl} @{" DisableWinDDListBoxes " Link DisableWinDDListBoxes} @{" EnableDDListBox " Link EnableDDListBox} @{" MakeDDListBox " Link MakeDDListBox} @{" MakeSubDDListBox " Link MakeSubDDListBox} @{" RestoreDDListBoxStatus " Link RestoreDDListBoxStatus} @{" StoreDDListBoxStatus " Link StoreDDListBoxStatus} @endnode @node DisableWinDDListBoxes "DisableWinDDListBoxes function" Function prototype: void DisableWinDDListBoxes(GuiWindow *c, BOOL redraw); Description: Disable all FoxGui list boxes in the specified FoxGui window. See @{" DisableDDListBox " Link DisableDDListBox} for exact details about what this entails. Parameters: c: A pointer to the FoxGui window whose drop-down list boxes are to be disabled. redraw: If TRUE, redraw the drop-down list boxes so that they appear disabled. If you're about to close the window then this may as well be FALSE. Known bugs: None. See also: @{" DisableAllDDListBoxes " Link DisableAllDDListBoxes} @{" DisableDDListBox " Link DisableDDListBox} @{" EnableWinDDListBoxes " Link EnableWinDDListBoxes} @{" MakeDDListBox " Link MakeDDListBox} @{" MakeSubDDListBox " Link MakeSubDDListBox} @{" RestoreDDListBoxStatus " Link RestoreDDListBoxStatus} @{" StoreDDListBoxStatus " Link StoreDDListBoxStatus} @endnode @node EnableAllDDListBoxes "EnableAllDDListBoxes function" Function prototype: void EnableAllDDListBoxes(BOOL redraw); Description: Enable all FoxGui drop-down list boxes in the current application. Parameters: redraw: If TRUE, redraw the drop-down list boxes so that they appear enabled. For a description of how drop-down list boxes look when disabled, see the @{" DisableDDListBox " Link DisableDDListBox} function. Known bugs: None. See also: @{" DisableAllDDListBoxes " Link DisableAllDDListBoxes} @{" EnableDDListBox " Link EnableDDListBox} @{" EnableWinDDListBoxes " Link EnableWinDDListBoxes} @{" MakeDDListBox " Link MakeDDListBox} @{" MakeSubDDListBox " Link MakeSubDDListBox} @{" RestoreDDListBoxStatus " Link RestoreDDListBoxStatus} @{" StoreDDListBoxStatus " Link StoreDDListBoxStatus} @endnode @node EnableDDListBox "EnableDDListBox function" Function prototype: void EnableDDListBox(DDListBox *p, BOOL redraw); Description: Enable the specified FoxGui drop-down list box. When drop-down list boxes are first created they are automatically enabled so you only need to call this function to re-enable one that has been disabled. Parameters: p: A pointer to the drop-down list box to enable. redraw: If TRUE, redraw it so that it appears enabled. Known bugs: None. See also: @{" DisableDDListBox " Link DisableDDListBox} @{" EnableAllDDListBoxes " Link EnableAllDDListBoxes} @{" EnableControl " Link EnableControl} @{" EnableWinDDListBoxes " Link EnableWinDDListBoxes} @{" MakeDDListBox " Link MakeDDListBox} @{" MakeSubDDListBox " Link MakeSubDDListBox} @{" RestoreDDListBoxStatus " Link RestoreDDListBoxStatus} @{" StoreDDListBoxStatus " Link StoreDDListBoxStatus} @endnode @node EnableWinDDListBoxes "EnableWinDDListBoxes function" Function prototype: void EnableWinDDListBoxes(GuiWindow *c, BOOL redraw); Description: Enable all FoxGui drop-down list boxes in the specified FoxGui window. Parameters: c: A pointer to a FoxGui window whose drop-down list boxes you wish to enable. redraw: If TRUE, redraw the list boxes to make them appear enabled. Known bugs: None. See also: @{" DisableWinDDListBoxes " Link DisableWinDDListBoxes} @{" EnableAllDDListBoxes " Link EnableAllDDListBoxes} @{" EnableDDListBox " Link EnableDDListBox} @{" MakeDDListBox " Link MakeDDListBox} @{" MakeSubDDListBox " Link MakeSubDDListBox} @{" RestoreDDListBoxStatus " Link RestoreDDListBoxStatus} @{" StoreDDListBoxStatus " Link StoreDDListBoxStatus} @endnode @node MakeDDListBox "MakeDDListBox function" Function prototype: DDListBox *MakeDDListBox(void *Parent, int x, int y, int len, int buflen, int MaxHeight, int BorderCol, int Bcol, int Tcol, int id, char *prestr, char *poststr, short (*callfn) (DDListBox*), long flags); Description: Make a new FoxGui drop-down list box. Parameters: Parent: A pointer to an open FoxGui window or frame in which to put the new drop-down list box. x: The x coordinate in pixels of the left edge of the drop-down list box relative to the left edge of the window/frame. y: The y coordinate in pixels of the top edge of the drop-down list box relative to the top edge of the window/frame. len: The length in pixels of the text portion of the list box (A drop-down list box looks like an edit box with a button on the right hand end which is used to drop the list). The button is a fixed width (17 pixels) so the total length of the drop-down list box is len+17. buflen: The number of characters to reserve for the text buffer - this limits the length of the string that can be shown in the text portion of the list box and currently has a maximum value of 256 which should be more than enough. You do not need to allow for the NULL terminator - this function will automatically allocate one more character than you specify to allow for this so you could just set buflen to the strlen() of the longest item that you're going to put in the drop-down list. MaxHeight: The maximum number of lines to show at a time when the list box is dropped. For example, if you set this to 5 and the list box contains more than 5 items then only five will be visible in the list when you drop it but the list will have scroll buttons and a drag-bar to allow you to scroll through the other items. When you create a list box, it will check whether there is enough space on the screen below the list box in which to drop the box with your specified MaxHeight and if not then it will check to see whether there's room above the drop-down list box to "drop" the list upwards. If there's not enough room to "drop" the list in either direction with your specified MaxHeight then MakeDDListBox will fail. If you are going to make this a "popup" list box with the function @{" SetDDListBoxPopup " Link SetDDListBoxPopup} then you can safely set MaxHeight to 0. BorderCol: If the THREED flag is specified in the flags parameter then the border around the list box is drawn in the current Gui Pens (which can be changed by calling @{" SetGuiPens " Link SetGuiPens}) and this parameter is ignored. If the THREED flag is not specified then a simple 2 dimensional border is drawn around the drop-down list box in the pen colour specified in this parameter. Bcol: The background pen colour for the text portion of the drop-down list box. (Ignored prior to Intuition version 37). Tcol: The pen colour for the text within the text portion of the drop-down list box as well as the pre-text and post-text (see the prestr and poststr parameters). id: This parameter doesn't affect the way the drop-down list box looks or works in any way but gets stored as part of the drop-down list box structure and can be found at any time using the @{" GetDDListBoxID " Link GetDDListBoxID} macro. This is used in an entirely analogous way to the id parameter for edit boxes (see the @{" MakeEditBox " Link MakeEditBox} function for details). prestr: Text to appear to the left of the drop-down list box. See the prestr parameter in the @{" MakeEditBox " Link MakeEditBox} function for more details. poststr: Text to appear to the right of the drop-down list box. See the poststr parameter in the @{" MakeEditBox " Link MakeEditBox} function for more details. callfn: A pointer to a function to call when the user selects an item in a drop-down list box. There are a number of ways a user can do this and hence a number of ways to trigger this function but whichever method the user uses to pick an item, the result is always the same and it isn't important for the function to know how it was triggered. The prototype for the function should be as follows:- short MyDDListBoxFn (DDListBox *lb) The function will be sent a pointer to the drop-down list box but no indication of which item was picked. However, you can find out which item was picked from within the function by calling the @{" GetDDListBoxText " Link GetDDListBoxText} macro. See the @{" MakeEditBox " Link MakeEditBox} function for an example of how to use the id parameter for dealing with arrays of drop-down list boxes from within the call-back function. The return value of this call-back function isn't currently used by FoxGui but for future compatibility you should return GUI_CONTINUE. flags: Only three flags are currently available for use with drop-down list boxes: @{" S_AUTO_SIZE " Link S_AUTO_SIZE}, THREED and DD_CLEAR. If the THREED flag is specified then the border around the list box will be drawn (using the Gui pen colours) in such a way as to make it look as though it's pressed into the screen. If the THREED flag is not specified then the border will be a simple box around the edge in the specified BorderCol. DD_CLEAR specifies that the drop-down list box will be clear (i.e. see-through). In other words, the background colour of the drop-down list box will be the colour of the window or frame in which it was created. Returns: If successful, a pointer to a new FoxGui drop-down list box. NULL otherwise. Known bugs: None. See also: @{" AddToDDListBox " Link AddToDDListBox} @{" AssociateDDListBox " Link AssociateDDListBox} @{" ClearDDListBox " Link ClearDDListBox} @{" DestroyDDListBox " Link DestroyDDListBox} @{" DisableDDListBox " Link DisableDDListBox} @{" EnableDDListBox " Link EnableDDListBox} @{" MakeSubDDListBox " Link MakeSubDDListBox} @{" RemoveFromDDListBox " Link RemoveFromDDListBox} @{" RestoreDDListBoxStatus " Link RestoreDDListBoxStatus} @{" SetDDListBoxPopup " Link SetDDListBoxPopup} @{" SortDDListBox " Link SortDDListBox} @{" StoreDDListBoxStatus " Link StoreDDListBoxStatus} @{" GetDDListBoxID " Link GetDDListBoxID} @{" GetDDListBoxText " Link GetDDListBoxText} @{" SetDDListBoxText " Link SetDDListBoxText} @{" MakeEditBox " Link MakeEditBox} @endnode @node MakeSubDDListBox "MakeSubDDListBox function" Function prototype: DDListBox *MakeSubDDListBox(DDListBox *lb, char *string, int left, int top, int width, int height, int id, short (*callfn)(DDListBox*)); Description: Rather like menus which can have sub-menus, so drop-down list boxes can have sub-list boxes. Creating a sub-list box adds an item to a drop-down list box which, when selected, (rather than populating the text part of the drop-down list box) pops up another list of options from which the user must then select an item which will be used to populate the text part of the drop-down list box. Unlike menus, there is no limit to the number of levels a drop-down list box can have i.e. a sub-list box may in turn have items which, when selected open further sub-list boxes. Most functions which can be applied to drop-down list boxes can also be applied to sub-list boxes. For example, you add items to a sub-list box using the @{" AddToDDListBox " Link AddToDDListBox} function exactly as you do for drop-down list boxes. Sub-list boxes can also be associated using the @{" AssociateDDListBox " Link AssociateDDListBox} function. By their very nature, sub-list boxes are pop-up so there is no need to use the @{" SetDDListBoxPopup " Link SetDDListBoxPopup} function unless you want to later change where the list will pop-up. Parameters: lb: A pointer to an existing FoxGui drop-down list box to which to add the sub-list box. string: An item to add to the drop-down list box specified in lb which, when selected will trigger the sub-list box. It is a good idea to indicate somehow in the text you supply that this item triggers a sub-list box. I usually use the "»" character (created by pressing Alt-0) at the end of the text to indicate this. left: Sub-list boxes behave like pop-up list boxes (see @{" SetDDListBoxPopup " Link SetDDListBoxPopup}) so they need to be told where to appear on the screen. Like pop-up list boxes, they aren't constrained by the dimensions of the window they are created in but they are constrained by the dimensions of the screen that window appears on. This parameter specifies the left edge of the list when it pops up and is offset from the left edge of the screen (not the window). top: The top edge of the list when it pops up, offset from the top edge of the screen. width: The width in pixels of the list when it pops up. If you specify -1 for the width, the Gui will calculate the width necessary for all items in the list to be shown without being truncated and will use that width for the list box when it pops up. The calculation actually takes place when the list box pops up (not when you call this function) so that items added to or removed from the list after calling this function are also taken into account. This does make dropping the list marginally slower especially if there is a large number of items in the list but it means that in an application where the user can choose the font, you don't have to worry about calculating how wide you want the box to be - FoxGui will work it out for you. Note that if the width is set to -1, the left parameter is ignored because the Gui will have to calculate where to place the left edge of the box so that it will fit on the screen. height: Rather like the MaxHeight parameter to @{" MakeDDListBox " Link MakeDDListBox}, this is the height of the list when it pops up but is specified in lines of text - not pixels. If the left, top, width and height parameters are such that the area required will go beyond the boundaries of the screen, the function will fail. id: See @{" MakeDDListBox " Link MakeDDListBox} or @{" MakeEditBox " Link MakeEditBox} for details. callfn: A pointer to a function to call when an item is selected from the new sub-list box. See the callfn parameter to the function @{" MakeDDListBox " Link MakeDDListBox} for details. Returns: If successful, a pointer to the new sub-list box is returned. If not, NULL is returned. Known bugs: None. See also: @{" AddToDDListBox " Link AddToDDListBox} @{" AssociateDDListBox " Link AssociateDDListBox} @{" ClearDDListBox " Link ClearDDListBox} @{" DestroyAllDDListBoxes " Link DestroyAllDDListBoxes} @{" DestroyDDListBox " Link DestroyDDListBox} @{" DestroyWinDDListBoxes " Link DestroyWinDDListBoxes} @{" DisableAllDDListBoxes " Link DisableAllDDListBoxes} @{" DisableDDListBox " Link DisableDDListBox} @{" DisableWinDDListBoxes " Link DisableWinDDListBoxes} @{" EnableAllDDListBoxes " Link EnableAllDDListBoxes} @{" EnableDDListBox " Link EnableDDListBox} @{" EnableWinDDListBoxes " Link EnableWinDDListBoxes} @{" MakeDDListBox " Link MakeDDListBox} @{" RemoveFromDDListBox " Link RemoveFromDDListBox} @{" RestoreDDListBoxStatus " Link RestoreDDListBoxStatus} @{" SortDDListBox " Link SortDDListBox} @{" StoreDDListBoxStatus " Link StoreDDListBoxStatus} @{" GetDDListBoxID " Link GetDDListBoxID} @endnode @node RestoreDDListBoxStatus "RestoreDDListBoxStatus function" Function prototype: void RestoreDDListBoxStatus(BOOL redraw); Description: Restores the enabled/disabled status of every drop-down list box to it's status when @{" StoreDDListBoxStatus " Link StoreDDListBoxStatus} was last called. If StoreDDListBoxStatus has not been called since the last call to RestoreDDListBoxStatus then this function does nothing. Parameters: redraw: If TRUE, redraw all of the drop-down list boxes so that they look as they should with their restored status. Known bugs: None. See also: @{" DisableAllDDListBoxes " Link DisableAllDDListBoxes} @{" DisableDDListBox " Link DisableDDListBox} @{" DisableWinDDListBoxes " Link DisableWinDDListBoxes} @{" EnableAllDDListBoxes " Link EnableAllDDListBoxes} @{" EnableDDListBox " Link EnableDDListBox} @{" EnableWinDDListBoxes " Link EnableWinDDListBoxes} @{" MakeDDListBox " Link MakeDDListBox} @{" StoreDDListBoxStatus " Link StoreDDListBoxStatus} @endnode @node RemoveFromDDListBox "RemoveFromDDListBox function" Function prototype: BOOL RemoveFromDDListBox(DDListBox *list, char *str); Description: Remove the specified item from the specified drop-down list box. Parameters: list: The drop-down list box from which you want to remove an item. str: The text of the item to remove. This must exactly match the text given when the item was added to the drop-down list box but needn't be the same string. In other words, the pointers do not need to match but the text must. Returns: TRUE for success, FALSE for failure. Known bugs: None. See also: @{" AddToDDListBox " Link AddToDDListBox} @{" ClearDDListBox " Link ClearDDListBox} @{" MakeDDListBox " Link MakeDDListBox} @{" MakeSubDDListBox " Link MakeSubDDListBox} @endnode @node SetDDListBoxPopup "SetDDListBoxPopup function" Function prototype: BOOL SetDDListBoxPopup(DDListBox *l, int x, int y, int width, int height); Description: Usually when you click on the button on the right hand end of the text portion of a drop-down list, the list will drop immediately below the button (or immediately above if the drop-down list box is close to the bottom of the screen). The SetDDListBoxPopup allows you to specify where the list box will pop up when the button is pressed. Parameters: l: A pointer to the drop-down list box which is to pop up rather than drop down. x: The distance in pixels between the left edge of the screen and the left edge of the area where you want the list to pop up. y: The distance in pixels between the top edge of the screen and the top edge of the area where you want the list to pop up. Note that the x and y parameters are both relative to the screen not the window. width: The width in pixels of the list when it pops up. If you specify -1 for the width, the Gui will calculate the width necessary for all items in the list to be shown without being truncated and will use that width for the list box when it pops up. The calculation actually takes place when the list box pops up (not when you call this function) so that items added to or removed from the list after calling this function are also taken into account. This does make dropping the list marginally slower especially if there is a large number of items in the list but it means that in an application where the user can choose the font, you don't have to worry about calculating how wide you want the box to be - FoxGui will work it out for you. Note that if the width is set to -1, the x parameter is ignored because the Gui will have to calculate where to place the left edge of the box so that it will fit on the screen. height: The height (in lines of text) of the list when it pops up. This is rather like the MaxHeight parameter to the function @{" MakeDDListBox " Link MakeDDListBox}. Returns: TRUE for success, FALSE for failure. Note that this function will fail if the area described in the x, y, width and height parameters extends beyond the boundary of the screen. Known bugs: None. See also: @{" MakeDDListBox " Link MakeDDListBox} @{" MakeSubDDListBox " Link MakeSubDDListBox} @endnode @node SortDDListBox "SortDDListBox function" Function prototype: void SortDDListBox(DDListBox *p, int flags); Description: Sort the items in the specified drop-down list box into the order specified by the flags supplied. This will have no immediately visible effect on the drop-down list box but will affect the order in which the items are shown next time the user drops the list. Parameters: p: A pointer to a FoxGui drop-down list box whose items are to be sorted. flags: The available flags are NUM_ASCENDING, NUM_DESCENDING, ASCENDING, DESCENDING and IGNORE_CASE. ASCENDING and DESCENDING specify that sorting should be alphabetic and should be ascending or descending respectively. NUM_ASCENDING and NUM_DESCENDING specify that the sorting should be numeric - i.e. treat the text as numbers. The difference is that alphabetically, the string "02" would come before the string "1" whereas if the strings were converted to numbers, the correct numerical order would be obtained. The IGNORE_CASE flag, when combined with either of the alphabetic flags ASCENDING or DESCENDING causes the case of the characters to be ignored when sorting (without this, the entire alphabet of upper case characters is considered to come before any of the lower case characters). If no flags are specified, the DESCENDING flag is assumed. Known bugs: None. See also: @{" AddToDDListBox " Link AddToDDListBox} @{" MakeDDListBox " Link MakeDDListBox} @{" MakeSubDDListBox " Link MakeSubDDListBox} @endnode @node StoreDDListBoxStatus "StoreDDListBoxStatus function" Function prototype: void StoreDDListBoxStatus(void); Description: Stores the status (enabled or disabled) of every FoxGui drop-down list box in the application. You would typically do this if you wanted to temporarily disable all of the drop-down list boxes and then at a later point return each to it's previous state without having to know what the status of each was and reset them all individually. Your code might look like this: StoreDDListBoxStatus(); DisableAllDDListBoxes(TRUE); // Some code during which the user mustn't be able to edit any drop-down // list boxes... // End of uninteruptable code. RestoreDDListBoxStatus(TRUE); Known bugs: None. See also: @{" DisableAllDDListBoxes " Link DisableAllDDListBoxes} @{" DisableDDListBox " Link DisableDDListBox} @{" DisableWinDDListBoxes " Link DisableWinDDListBoxes} @{" EnableAllDDListBoxes " Link EnableAllDDListBoxes} @{" EnableDDListBox " Link EnableDDListBox} @{" EnableWinDDListBoxes " Link EnableWinDDListBoxes} @{" MakeDDListBox " Link MakeDDListBox} @{" MakeSubDDListBox " Link MakeSubDDListBox} @{" RestoreDDListBoxStatus " Link RestoreDDListBoxStatus} @endnode @node GetDDListBoxID "GetDDListBoxID macro" Macro prototype: int GetDDListBoxID(DDListBox *l) Macro definition: #define GetDDListBoxID(l) (l)->id Description: Returns the id of the specified drop-down list box, as supplied to @{" MakeDDListBox " Link MakeDDListBox} or @{" MakeSubDDListBox " Link MakeSubDDListBox} when the drop-down list box was created. See @{" MakeDDListBox " Link MakeDDListBox} or @{" MakeEditBox " Link MakeEditBox} for details. Parameters: l: A pointer to the FoxGui drop-down list box whose id you want to know. Returns: The id of the specified drop-down list box. See also: @{" GetEditBoxID " Link GetEditBoxID} @{" MakeDDListBox " Link MakeDDListBox} @{" MakeEditBox " Link MakeEditBox} @{" MakeSubDDListBox " Link MakeSubDDListBox} @{" Warnings on the use of macros " Link MacroWarnings} @endnode @node GetDDListBoxText "GetDDListBoxText macro" Macro prototype: char *GetDDListBoxText(DDListBox *l) Macro definition: #define GetDDListBoxText(l) GetEditBoxText(l) Description: Returns a pointer to a NULL terminated string containing the text currently displayed in the text portion of a drop-down list box. Passing a sub-list box as a parameter to this macro would be meaningless. Parameters: l: A pointer to the drop-down list box whose current text you want to know. Returns: A pointer to a NULL terminated text string containing the text currently shown in the text portion of the drop-down list box. The pointer returned is a pointer to the actual buffer used by the drop-down list box so you should never directly modify this string in any way. If you keep a copy of the pointer you should also remember that it will become invalid when the drop-down list box is destroyed. The safest thing to do is make your own copy of the string using a function such as strcpy. If this function fails, NULL will be returned. If there is no text in the box then an empty string will be returned. Remember that the text may not necessarily match an item in the drop-down list box itself. This will happen if no item has been selected, the item has been selected from a sub-list box, the item selected has since been removed from the list or the text has been set to a non-matching value by calling the macro @{" SetDDListBoxText " Link SetDDListBoxText}. See also: @{" GetEditBoxText " Link GetEditBoxText} @{" MakeDDListBox " Link MakeDDListBox} @{" MakeSubDDListBox " Link MakeSubDDListBox} @{" RemoveFromDDListBox " Link RemoveFromDDListBox} @{" SetDDListBoxText " Link SetDDListBoxText} @{" Warnings on the use of macros " Link MacroWarnings} @endnode @node SetDDListBoxText "SetDDListBoxText macro" Macro prototype: BOOL SetDDListBoxText(DDListBox *l, char *c) Macro definition: #define SetDDListBoxText(l,c) SetEditBoxText(l,c) Description: Set the text shown in the text portion of a drop-down list box. Note that the text need not match any of the items available in the list for selection by the user although I can't really see why you would want to do that. Parameters: l: A pointer to the drop-down list box whose text you want to set. c: A pointer to a NULL terminated text string containing the text you wish to put in the text portion of the drop-down list box. A copy will be made of the string supplied so there is no need to preserve the string passed after calling the function. Returns: TRUE for success, FALSE for failure. See also: @{" SetEditBoxText " Link SetEditBoxText} @{" MakeDDListBox " Link MakeDDListBox} @{" MakeSubDDListBox " Link MakeSubDDListBox} @{" GetDDListBoxText " Link GetDDListBoxText} @{" Warnings on the use of macros " Link MacroWarnings} @endnode @node OutputBoxes "FoxGui Outputbox functions" Output boxes provide a convenient way of placing text or data onto a FoxGui window. If you want a piece of static text placed in a window (for example a title or label of some description) you can make an output box at that position and then set the output box text using one of the functions below. Alternatively, if you want to display a piece of data that may change during the time the program is running, an output box is perfect for that too. Just make the output box and then use one of the functions below to set the output box text each time it needs to change. As with edit boxes, TEXT, INT and FLOAT types are supported and the number of decimal places for FLOAT types can be specified. The following outputbox functions are currently available :- @{" DestroyAllOutputBoxes " Link DestroyAllOutputBoxes} @{" DestroyOutputBox " Link DestroyOutputBox} @{" DestroyWinOutputBoxes " Link DestroyWinOutputBoxes} @{" MakeOutputBox " Link MakeOutputBox} @{" SetOutputBoxCols " Link SetOutputBoxCols} @{" SetOutputBoxDP " Link SetOutputBoxDP} @{" SetOutputBoxFloat " Link SetOutputBoxFloat} @{" SetOutputBoxInt " Link SetOutputBoxInt} @{" SetOutputBoxText " Link SetOutputBoxText} The following outputbox functions are defined as macros :- @{" GetOutputBoxID " Link GetOutputBoxID} @endnode @node DestroyAllOutputBoxes "DestroyAllOutputBoxes function" Function prototype: void DestroyAllOutputBoxes(BOOL refresh); Description: Destroy all FoxGui output boxes in the current application, Freeing all associated resources. Parameters: refresh: If TRUE, the output boxes will disappear (i.e. their imagery will be removed from the windows they were made in). You would typically set this to FALSE only if you were about to close the window anyway (there's no point in updating the imagery for a window which is about to close since closing the window will remove the imagery). Known bugs: None. See also: @{" DestroyOutputBox " Link DestroyOutputBox} @{" DestroyWinOutputBoxes " Link DestroyWinOutputBoxes} @{" MakeOutputBox " Link MakeOutputBox} @endnode @node DestroyOutputBox "DestroyOutputBox function" Function prototype: void DestroyOutputBox(OutputBox *p, BOOL refresh); Description: Destroy the specified output box, freeing all associated resources. Parameters: p: A pointer to the output box to destroy. refresh: If TRUE, the output box will disappear (i.e. it's imagery will be removed from the window it was made in). You would typically set this to FALSE only if you were about to close the window anyway (there's no point in updating the imagery for a window which is about to close since closing the window will remove the imagery). Known bugs: None. See also: @{" Destroy " Link Destroy} @{" DestroyAllOutputBoxes " Link DestroyAllOutputBoxes} @{" DestroyWinOutputBoxes " Link DestroyWinOutputBoxes} @{" MakeOutputBox " Link MakeOutputBox} @endnode @node DestroyWinOutputBoxes "DestroyWinOutputBoxes function" Function prototype: void DestroyWinOutputBoxes(GuiWindow *c, BOOL refresh); Description: Destroy all FoxGui output boxes in the specified window. Parameters: c: A pointer to the window whose output boxes are to be destroyed. refresh: If TRUE, the output boxes will disappear (i.e. their imagery will be removed from the window). You would typically set this to FALSE only if you were about to close the window anyway (there's no point in updating the imagery for a window which is about to close since closing the window will remove the imagery). Known bugs: None. See also: @{" DestroyAllOutputBoxes " Link DestroyAllOutputBoxes} @{" DestroyOutputBox " Link DestroyOutputBox} @{" MakeOutputBox " Link MakeOutputBox} @endnode @node MakeOutputBox "MakeOutputBox function" Function prototype: OutputBox *MakeOutputBox(void *Parent, int x, int y, int width, int len, int Bcol, int Tcol, int id, char *prestr, char *poststr, struct TextAttr *font, long flags); Description: Create a new output box in the specified window or frame. Parameters: Parent: A pointer to the FoxGui window or frame in which to create the output box. x: The coordinate of the left edge of the new output box relative to the left hand edge of the specified window/frame. y: The coordinate of the top edge of the new output box relative to the top edge of the specified window/frame. Note that this is from the very top of a window so a y coordinate of 0 will cause the output box to be at least partly obscured by the window's title bar if it has one. width: The width of the output box in pixels. This width includes the border if one is specified (see flags below). len: The maximum length (in characters) of text that can be shown in the output box. This will be used to allocate memory for the text buffer so you should try not to set this higher than you need it. This number cannot be more than 256. Bcol: The pen colour for the output box border if a two dimensional border is specified (see flags below). Tcol: The pen colour for the text within the output box as well as the pre-text and post-text (see the prestr and poststr parameters). id: Sets the id of the output box which can be retrieved at any time with the @{" GetOutputBoxID " Link GetOutputBoxID} macro. The id for an output box is used in exactly the same way as the id of an edit box. See @{" MakeEditBox " Link MakeEditBox} for a full description. prestr: A NULL terminated text string containing text that you want to appear to the left of the output box. Typically, the prestr would describe the output shown in the box. For example, if the ouput box was designed to show the result of a calculation then you might set the prestr to "Result:" so that you only have to put the actual result into the output box itself. If you do not want a prestr, set this to NULL. poststr: A NULL terminated text string containing text that you want to appear to the right of the output box. Continuing the example used for prestr above, if the calculation was of the speed of a rocket in metres per second, you might set the poststr to "m/s". If you do not want a poststr, set this to NULL. font: A pointer to an initialised Intuition TextAttr structure which specifies the font to be used for text in the output box. If font is NULL then the current screen's font is used. If the current screen is a FoxGui screen then you may have specified that when calling @{" OpenGuiScreen " Link OpenGuiScreen}. If the screen is a public screen then you will have no control over that font so it is advisible to specify the font you require when calling MakeOutputBox in a window on a public screen. flags: Currently six flags are available for use with output boxes: THREED, NO_BORDER, JUSTIFY_LEFT, JUSTIFY_CENTRE, JUSTIFY_RIGHT and @{" S_AUTO_SIZE " Link S_AUTO_SIZE}. If the NO_BORDER flag is specified then the output box will not have a border. If the THREED flag is specified then the output box will have a three dimensional border drawn in the current Gui pens (these can be modified by calling @{" SetGuiPens " Link SetGuiPens}). If neither flag is specified then the output box will have a two dimensional border in the specified BCol. The three JUSTIFY_ flags are mutually exclusive. At most one of them should be specified. If the JUSTIFY_LEFT flag is set then any text placed in the output box with the functions @{" SetOutputBoxText " Link SetOutputBoxText}, @{" SetOutputBoxFloat" Link SetOutputBoxFloat} or @{" SetOutputBoxInt" Link SetOutputBoxInt} will begin at the left edge of the output box. If JUSTIFY_CENTRE is specified then text will appear centred within the bounds of the output box and if JUSTIFY_RIGHT is selected then the right edge of the text will be aligned with the right edge of the output box. If none of the JUSTIFY_ flags is selected then JUSTIFY_LEFT is used by default. Starting with release 2.0, whichever justification method is selected, the text will be clipped appropriately to ensure that it never extends beyond the border of the output box. If the output box is resized (due to a window resizing) then some of the clipped text may become visible or more may be clipped. Returns: If successful, a pointer to the new output box, otherwise NULL. Known bugs: None. See also: @{" DestroyAllOutputBoxes " Link DestroyAllOutputBoxes} @{" DestroyOutputBox " Link DestroyOutputBox} @{" DestroyWinOutputBoxes " Link DestroyWinOutputBoxes} @{" SetOutputBoxCols " Link SetOutputBoxCols} @{" SetOutputBoxDP " Link SetOutputBoxDP} @{" SetOutputBoxFloat " Link SetOutputBoxFloat} @{" SetOutputBoxInt " Link SetOutputBoxInt} @{" SetOutputBoxText " Link SetOutputBoxText} @{" GetOutputBoxID " Link GetOutputBoxID} @endnode @node SetOutputBoxCols "SetOutputBoxCols function" Function prototype: void SetOutputBoxCols(OutputBox *ob, int Bcol, int Tcol, BOOL refresh); Description: Modify the colours of an existing FoxGui output box. Parameters: ob: A pointer to the output box whose colours are to be modified. refresh: If TRUE, redraw the output box in its new colours. The Bcol and Tcol parameters are identical to the Bcol and Tcol parameters passed to @{" MakeOutputBox " Link MakeOutputBox}. Known bugs: None. See also: @{" MakeOutputBox " Link MakeOutputBox} @{" SetOutputBoxDP " Link SetOutputBoxDP} @{" SetOutputBoxFloat " Link SetOutputBoxFloat} @{" SetOutputBoxInt " Link SetOutputBoxInt} @{" SetOutputBoxText " Link SetOutputBoxText} @endnode @node SetOutputBoxDP "SetOutputBoxDP function" Function prototype: void SetOutputBoxDP(OutputBox *p, int dp); Description: Set the number of decimal places which will be shown when a floating point (non integral) number is shown in the output box specified. This function will not affect text placed in the output box using the functions @{" SetOutputBoxInt " Link SetOutputBoxInt} and @{" SetOutputBoxText " Link SetOutputBoxText}. Only text set using the function @{" SetOutputBoxFloat " Link SetOutputBoxFloat} is affected. Parameters: p: A pointer to the output box. dp: The number of figures to show after the decimal point when floating point numbers are displayed. Known bugs: None. See also: @{" MakeOutputBox " Link MakeOutputBox} @{" SetOutputBoxCols " Link SetOutputBoxCols} @{" SetOutputBoxFloat " Link SetOutputBoxFloat} @endnode @node SetOutputBoxFloat "SetOutputBoxFloat function" Function prototype: void SetOutputBoxFloat(OutputBox *p, float num); Description: This function converts the floating point number passed to it into text and places that text in the output box specified. You might use this to display the result of a calculation in a window. If you want to limit the number of decimal places shown in the output box without having to round the number, you can do so by calling the function @{" SetOutputBoxDP " Link SetOutputBoxDP}. The justification specified in the flags parameter of @{" MakeOutputBox " Link MakeOutputBox} is respected by this function. Parameters: p: A pointer to the output box whose text is to be set or replaced. num: The number to place in the output box. Known bugs: None. See also: @{" MakeOutputBox " Link MakeOutputBox} @{" SetOutputBoxDP " Link SetOutputBoxDP} @{" SetOutputBoxInt " Link SetOutputBoxInt} @{" SetOutputBoxText " Link SetOutputBoxText} @endnode @node SetOutputBoxInt "SetOutputBoxInt function" Function prototype: void SetOutputBoxInt(OutputBox *p, int num); Description: This function converts the integral number passed to it into text and places that text in the output box specified. You might use this to display the result of a calculation in a window. The justification specified in the flags parameter of @{" MakeOutputBox " Link MakeOutputBox} is respected by this function. Parameters: p: A pointer to the output box whose text is to be set or replaced. num: The number to place in the output box. Known bugs: None. See also: @{" MakeOutputBox " Link MakeOutputBox} @{" SetOutputBoxFloat " Link SetOutputBoxFloat} @{" SetOutputBoxText " Link SetOutputBoxText} @endnode @node SetOutputBoxText "SetOutputBoxText function" Function prototype: void SetOutputBoxText(OutputBox *p, char *text); Description: Set or modify the text of the specified output box to the text passed to this function. The justification specified in the flags parameter of @{" MakeOutputBox " Link MakeOutputBox} is respected by this function. Parameters: p: A pointer to the output box whose text is to be set or replaced. text: A pointer to the NULL terminated string to be placed into the output box. After calling the function SetOutputBoxText, it is not necessary to maintain the text string passed - the function will make it's own copy of the string. Known bugs: None. See also: @{" MakeOutputBox " Link MakeOutputBox} @{" SetOutputBoxFloat " Link SetOutputBoxFloat} @{" SetOutputBoxInt " Link SetOutputBoxInt} @endnode @node GetOutputBoxID "GetOutputBoxID macro" Macro prototype: int GetOutputBoxID(OutputBox *o) Macro definition: #define GetOutputBoxID(o) (o)->id Description: Returns the id of the specified output box. Output box ids are entirely analogous to edit box ids, a full description of which can be found in the function @{" MakeEditBox " Link MakeEditBox}. Parameters: p: A pointer to the output box whose id you want to know. Returns: The id of the output box specified. See also: @{" Warnings on the use of macros " Link MacroWarnings} @{" MakeOutputBox " Link MakeOutputBox} @endnode @node TabControls "FoxGui Tab Controls" Tab controls, like frames can be holders of other controls. It's difficult to explain to an Amiga user what a tab control is like because I've never seen them used in Amiga programs before. PC users may have seen them used in the options dialogue in Microsoft Word for Windows 6 or 7. Basically a tab control is a frame with a row of buttons along the top edge. Clicking on any of the buttons will change the contents of the frame. You may, for example, have a program that is highly configurable and hence has a lot of options the user can choose from. Let's say, for example that the user can change the screen mode that the program runs in, the pallette used for the screen and several other program specific options. The number of controls requiured to display all of these options may well be more than you can easily (or neatly) fit into a window (especially if the program is allowed to run in the basic Amiga Pal modes) so the answer is a tab control. You create a tab control with three frames (and hence three buttons). The frames in a tab control are always the same size as each other and directly on top of each other so that you only see one frame at a time. The first frame could contain the screen mode preferences, the second the pallette preferences and the third all of the other options. The three buttons could then be labelled "Screen", "Pallette" and "Other". When you create controls in a tab control frame you use the normal "Make" functions (MakeButton, MakeEditBox etc) but rather than passing a pointer to a GuiWindow as the first parameter, you pass a pointer to the frame in the tab control (see the @{" TabControlFrame " Link TabControlFrame} function). You do not need to write any code to handle what happens when the user clicks the buttons along the top edge of the tab control - this is automatically handled for you by FoxGui. When you click the first button, the contents of the first frame becomes visible. When you click the second button, the contents of the second frame becomes visible and the contents of the frame shown previously becomes invisible. Note that any type of control can be created in the frame of a tab control (including frames and further tab controls!) Rather than try in vain to describe this further, I'll leave it to you to look at the "Characters" program available for download from my web page (see @{" Suggestions " Link Suggestions} section for the address) which makes use of tab controls. The following tab control functions are currently available :- @{" DestroyAllTabControls " Link DestroyAllTabControls} @{" DestroyTabControl " Link DestroyTabControl} @{" DestroyWinTabControls " Link DestroyWinTabControls} @{" DisableTabControl " Link DisableTabControl} @{" EnableTabControl " Link EnableTabControl} @{" MakeTabControl " Link MakeTabControl} @{" TabControlFrame " Link TabControlFrame} @endnode @node DestroyAllTabControls "DestroyAllTabControls function" Function prototype: void DestroyAllTabControls(BOOL refresh); Description: Destroys all tab controls created by this application. Parameters: refresh: If TRUE, the tab controls will be removed from the windows in which they appear. This function is faster if refresh is FALSE but you should only use FALSE if you are about to close the windows in question. Otherwise tab controls will still appear to be present in the windows but the user will not be able to interact with them. Known bugs: None. See also: @{" DestroyTabControl " Link DestroyTabControl} @{" DestroyWinTabControls " Link DestroyWinTabControls} @endnode @node DestroyTabControl "DestroyTabControl function" Function prototype: void DestroyTabControl(TabControl *tc, BOOL refresh); Description: Destroys the specified tab control. Parameters: tc: A pointer to the tab control to be destroyed. refresh: If TRUE, the tab control is removed from the window. Only set this to FALSE if you are about to close the window. Known bugs: None. See also: @{" DestroyAllTabControls " Link DestroyAllTabControls} @{" DestroyWinTabControls " Link DestroyWinTabControls} @{" DisableTabControl " Link DisableTabControl} @{" MakeTabControl " Link MakeTabControl} @endnode @node DestroyWinTabControls "DestroyWinTabControls function" Function prototype: void DestroyWinTabControls(GuiWindow *w, BOOL refresh); Description: Destroy all tab controls contained in the specified FoxGui Window. Parameters: w: A pointer to the GuiWindow whose tab controls are to be destroyed. refresh: If TRUE, the window will be refreshed so that the tab controls disappear. Known bugs: None. See also: @{" DestroyAllTabControls " Link DestroyAllTabControls} @{" DestroyTabControl " Link DestroyTabControl} @endnode @node DisableTabControl "DisableTabControl function" Function prototype: void DisableTabControl(TabControl *tc); Description: Disables the buttons along the top edge of the specified tab control, thus preventing any other frame within the control from being brought to the front. This function does not disable any other controls created in the frame which is visible at the time this function is called. Parameters: tc: A pointer to the tab control to disable. Known bugs: None. See also: @{" EnableTabControl " Link EnableTabControl} @endnode @node EnableTabControl "EnableTabControl function" Function prototype: void EnableTabControl(TabControl *tc); Description: Enable a disabled tab control. Note that tab controls are already enabled when they are created. You only need to call this function to enable a tab control that was previously disabled by calling @{" DisableTabControl " Link DisableTabControl}. Parameters: tc: A pointer to the disabled tab control. Known bugs: None. See also: @{" DisableTabControl " Link DisableTabControl} @endnode @node MakeTabControl "MakeTabControl function" Function prototype: TabControl *MakeTabControl(void *Parent, int left, int top, int width, int height, int tcol, int fcol, int tabheight, short flags, int numtabs, ...); Description: Create a new tab control. Parameters: Parent: A pointer to the window or frame in which to create the new tab control. left: The left edge (in pixels) of the tab control relative to the left edge of the parent window/frame. top: The top edge (in pixels) of the row of buttons (tabs) which runs along the top edge of the tab control, relative to the top of the parent window/frame. width: The width (in pixels) of the tab control. height: The height (in pixels) of the framed part of the tab control. The overall height of the tab control will be height+tabheight. tcol: The colour to use for the text in the tabs. fcol: The background colour for the entire tab control. tabheight: The height (in pixels) of the tabs along the top edge of the control. flags: The following flags are currently available for tab controls :- TC_CLEAR, S_AUTO_SIZE. The TC_CLEAR flag causes the background colour of the tab control to be the colour of the window or frame in which it was created. The S_AUTO_SIZE flag causes the tab control to get resized if the parent (window or frame) is resized. numtabs: The number of tabs to create along the top edge of the control. For each of the tabs on your tab control (the number specified in numtabs) you must also pass the following data :- tabwidth: The width of the tab (in pixels). caption: A pointer to a text string containing the text to appear in that tab. For example, to create three tabs each of width 70 pixels with the captions "Screen", "Pallette" and "Other", the last 7 parameters to MakeTabControl would be :- (numtabs width caption width caption width caption) 3, 70, "Screen", 70, "Pallette", 70, "Other" Returns: If successful, a pointer to the new tab control. Otherwise NULL. Known bugs: None. See also: @{" DestroyTabControl " Link DestroyTabControl} @{" TabControlFrame " Link TabControlFrame} @endnode @node TabControlFrame "TabControlFrame function" Function prototype: Frame *TabControlFrame(TabControl *tc, int frameno); Description: Controls can be created in windows or in frames. A tab control is really just a series of frames so to create a control in a tab control, you first need to get a pointer to the frame. This function returns a pointer to a frame in a tab control. Parameters: tc: A pointer to a tab control. frameno: The frame number of the frame you want a pointer to. Note that the frame numbers start at zero so if you have a tab control with seven tabs, the frames will be numbered 0 - 6. Returns: If successful, a pointer to a frame within a tab control. Otherwise NULL. Note that if frameno is more than the number of frames in the tab control minus one (frames are numbered starting from zero) then this function will return NULL. Known bugs: None. See also: @{" MakeTabControl " Link MakeTabControl} @endnode @node Misc "FoxGui Miscelaneous functions" The following miscelaneous functions aren't directly related to any type of FoxGui control but are still very important. @{" InitGui " Link InitGui} and @{" GuiLoop " Link GuiLoop} for example are essential in all FoxGui programs (see the @{" Format of a FoxGui program " Link Format} section for details). It is worth browsing the other functions below because they could save you a lot of time and effort in developing equivalents yourself. The following miscelaneous functions are currently available :- @{" CheckMessages " Link CheckMessages} @{" Destroy " Link Destroy} @{" DisableControl " Link DisableControl} @{" DisableEverything " Link DisableEverything} @{" DrawLines " Link DrawLines} @{" EnableControl " Link EnableControl} @{" EnableEverything " Link EnableEverything} @{" EndGui " Link EndGui} @{" GetWindow " Link GetWindow} @{" GuiLoop " Link GuiLoop} @{" GuiMalloc " Link GuiMalloc} @{" GuiMessage " Link GuiMessage} @{" Hide " Link Hide} @{" InitGui " Link InitGui} @{" IntuiWindow " Link IntuiWindow} @{" LibVersion " Link LibVersion} @{" RegisterGadget " Link RegisterGadget} @{" RestoreEveryStatus " Link RestoreEveryStatus} @{" SetDelay " Link SetDelay} @{" SetGuiPens " Link SetGuiPens} @{" SetGuiPensFromPubScreen " Link SetGuiPensFromPubScreen} @{" SetPeriod " Link SetPeriod} @{" Show " Link Show} @{" StoreEveryStatus " Link StoreEveryStatus} @{" UnRegisterGadget " Link UnRegisterGadget} The following miscelaneous operations are currently defined as macros :- @{" GuiFree " Link GuiFree} @endnode @node CheckMessages "CheckMessages function" Function prototype: void CheckMessages(void); Description: Tells FoxGui to check for any pending messages and respond to them immediately. See the section on @{" Multi-threading " Link MultiThreading} for more information. Known bugs: None. See also: @{" Multi-threading " Link MultiThreading} @endnode @node Destroy "Destroy function" Function prototype: void Destroy(void *Control, BOOL refresh); Description: Destroys the specified control. This function is exactly equivalent to calling @{" DestroyFrame " Link DestroyFrame} or @{" DestroyButton " Link DestroyButton} with a pointer to a frame or a button respectively but works for any control including windows and screens. The only exceptions are menus, menu items and sub-menu items. Parameters: Control: A pointer to the control to destroy. refresh: If TRUE, refresh the parent window so that the control is visibly removed from the window. If you are in the process of destroying all of the controls in a window in order to close the window then you might want to set this to FALSE which will make the process faster. Known bugs: Can't be used to destroy menus, menu items or sub-menu items. See also: @{" DisableControl " Link DisableControl} @{" EnableControl " Link EnableControl} @{" GetWindow " Link GetWindow} @{" Hide " Link Hide} @{" Show " Link Show} @endnode @node DisableControl "DisableControl function" Function prototype: void DisableControl(void *Control, BOOL refresh); Description: Disables the specified control. Equivalent to calling @{" DisableButton " Link DisableButton}, @{" DisableListBox " Link DisableListBox} etc but works for any control except menus, menu items, sub-menu items, output boxes, screens, progress bars and frames. Passing a pointer to a GuiWindow is equivalent to calling @{" SleepPointer " Link SleepPointer} and passing a pointer to a timer is equivalent to calling @{" PauseTimer " Link PauseTimer}. Parameters: Control: A pointer to the control to disable. refresh: If TRUE, the control will be redrawn to appear disabled. For controls which have no imagery (such as timers) this parameter is ignored. Known bugs: None. See also: @{" Destroy " Link Destroy} @{" EnableControl " Link EnableControl} @{" GetWindow " Link GetWindow} @{" Hide " Link Hide} @{" Show " Link Show} @endnode @node DisableEverything "DisableEverything function" Function prototype: void DisableEverything(int redraw); Description: This function disables all FoxGui menus, pushbuttons, edit boxes and drop-down list boxes in the application. This function currently has no effect on list boxes, radio buttons or tick boxes. Parameters: redraw: If TRUE, all of the newly disabled controls get redrawn so that they appear disabled. Known bugs: None. See also: @{" EnableEverything " Link EnableEverything} @{" RestoreEveryStatus " Link RestoreEveryStatus} @{" StoreEveryStatus " Link StoreEveryStatus} @endnode @node DrawLines "DrawLines function" Function prototype: void DrawLines(GuiWindow *win, short *points, int count, int col); Description: Draw straight line(s) in the specified FoxGui window. Parameters: win: A pointer to a FoxGui window in which to draw the line(s). points: A pointer to an array of points describing the lines to be drawn. Each pair of numbers is treated as the x and y coordinates of a point relative to the top left of the specified window. Lines are drawn from the first point given to the second, from the second point to the third etc until lines have been drawn between count sets of coordinates. count: The number of points between which to draw lines. The points array should contain count sets of coordinates (i.e. count * 2 numbers). col: The colour in which to draw the lines. Known bugs: None. @endnode @node EnableControl "EnableControl function" Function prototype: void EnableControl(void *Control, BOOL refresh); Description: Enables the specified control. Equivalent to calling @{" EnableButton " Link EnableButton}, @{" EnableListBox " Link EnableListBox} etc but works for any control except menus, menu items, sub-menu items, output boxes, screens, progress bars and frames. Passing a pointer to a GuiWindow is equivalent to calling @{" WakePointer " Link WakePointer} and passing a pointer to a timer is equivalent to calling @{" UnpauseTimer " Link UnpauseTimer}. Parameters: Control: A pointer to the control to enable. refresh: If TRUE, the control will be redrawn to appear enabled. For controls which have no imagery (such as timers) this parameter is ignored. Known bugs: None. See also: @{" Destroy " Link Destroy} @{" DisableControl " Link DisableControl} @{" GetWindow " Link GetWindow} @{" Hide " Link Hide} @{" Show " Link Show} @endnode @node EnableEverything "EnableEverything function" Function prototype: void EnableEverything(int redraw); Description: This function enables all FoxGui menus, pushbuttons, edit boxes and drop-down list boxes in the application. This function currently has no effect on list boxes, radio buttons or tick boxes. Parameters: redraw: If TRUE, all of the newly enabled controls get redrawn so that they appear enabled. Known bugs: None. See also: @{" DisableEverything " Link DisableEverything} @{" RestoreEveryStatus " Link RestoreEveryStatus} @{" StoreEveryStatus " Link StoreEveryStatus} @endnode @node EndGui "EndGui function" Function prototype: void EndGui(void); Description: This function should be called by a FoxGui program before it exits. It free's up all resources used by the FoxGui including closing the Intuition, Graphics and IFFParse libraries which were opened in @{" InitGui " Link InitGui}. If the FAST_MALLOCS flag was not specified when InitGui was called, it will also detect any memory allocations which have not been free'd and report this as an error (it isn't able to free those allocations for you because it's tracking doesn't extend to keeping a complete list of memory allocated by your application - it will, however, free any memory allocated by FoxGui itself which has not been free'd. For example, if you call EndGui when you still have a FoxGui screen open with a FoxGui window on it, EndGui will close the window and the screen and free up all the associated memory but if you've allocated memory from within your application using the GuiMalloc function, that won't be free'd but will be reported as an error to help you to debug your code). Any error messages shown by EndGui will be sent to the stderr stream and so will not be redirected if the program's output is sent to a file or to NIL: via the > operator. See @{" InitGui " Link InitGui} and @{" GuiMalloc " Link GuiMalloc} for more information. Known bugs: None. See also: @{" GuiLoop " Link GuiLoop} @{" GuiMalloc " Link GuiMalloc} @{" InitGui " Link InitGui} @{" GuiFree " Link GuiFree} @endnode @node GetWindow "GetWindow function" Function prototype: GuiWindow *GetWindow(void *Control); Description: Returns a pointer to the window in which the specified control was created. If the control was created in a frame or a tab control then a pointer to the window in which the frame or tab control was created is returned. Similarly if the control is in a frame which itself is in a frame which is in a tab control then a pointer to the window in which the tab control was created is returned. Parameters: Control: A pointer to the control. Note that the control may not be a menu, menu item, sub-menu item or screen. Returns: A pointer to the GuiWindow in which the control was created. Known bugs: Doesn't work for menus, menu items or sub-menu items. See also: @{" Destroy " Link Destroy} @{" DisableControl " Link DisableControl} @{" EnableControl " Link EnableControl} @{" Hide " Link Hide} @{" Show " Link Show} @endnode @node GuiLoop "GuiLoop function" Function prototype: void GuiLoop(void); Description: The GuiLoop function is where all of the Gui events are processed. You call it when you have set up all of the screens/windows/controls that you want the user to have access to when they first run your application and it handles all of the input events for the controls you have set up. When you create a control, you usually supply a pointer to a function as a parameter - for example when you create a button using the MakeButton function, one of the parameters is a pointer to a function to call when the button is clicked. It is the GuiLoop function which ensures that the correct functions are called when these events occur. These call-back functions can themselves create and destroy controls and when the call-back function returns it generally has to return one of two values - one specifying that GuiLoop should continue to process events for your existing windows and controls (and also for any new controls that you created from within the call-back function) and one that informs the GuiLoop function that you're all done and will cause GuiLoop to return. Known bugs: None. See also: @{" EndGui " Link EndGui} @{" InitGui " Link InitGui} @endnode @node GuiMalloc "GuiMalloc function" Function prototype: void *GuiMalloc(unsigned long NoOfBytes, unsigned long flags); Description: This function allocates memory. It is the function used internally within FoxGui to allocate memory whenever FoxGui needs it. I have made it available externally because it provides a little bit of control over memory allocation which is not available through other means. Memory allocated by the GuiMalloc function should be free'd with the @{" GuiFree " Link GuiFree} macro. GuiMalloc works in one of two ways depending upon whether the FAST_MALLOCS flag was specified in the call to @{" InitGui " Link InitGui}. One provides error checking code but is slow by comparison to the other which does not. It is suggested that you use the slower method while developing your programs (by passing 0 as the flags parameter to InitGui) and then when they are bug free and ready to release, change the call to InitGui to pass FAST_MALLOCS as the flags parameter to speed things up by removing the error checking code. If FAST_MALLOCS has not been specified, GuiMalloc works as follows: When you ask GuiMalloc to allocate some memory, it actually allocates extra bytes at the start and end of the memory you asked for and puts special characters in these bytes along with a record of the number of bytes allocated. Then, when you call GuiFree with a pointer to some memory to free it checks for those special characters immediately before and after the memory you allocated and returns an error if they are not there. This prevents you from attempting to free memory that you haven't allocated and memory that has become corrupted. If memory has become corrupted it's usually due to something like writing beyond the bounds of an array. In general, you wouldn't find out about this until your Amiga crashed due to some processes memory having been scribbled on by itself or another process but by using GuiMalloc and GuiFree there's a chance that you will be allerted to it sooner. Of course, this sort of protection isn't as good as that provided by running Enforcer and Mungwall but it doesn't require an MMU (which Enforcer does) and if a call to GuiFree fails, the Gui will tell you exactly which call failed by telling you the filename and line number of the offending GuiFree call. Parameters: NoOfBytes: The number of bytes of memory to allocate. flags: At the moment, the only available flag is MEMF_CLEAR which will cause all of the allocated memory to be set to zeros if specified. Returns: A pointer to the allocated memory or NULL for failure. It is essential that you check the return code of this function before using the memory - writing over NULL memory is very likely to cause a crash! Known bugs: None. See also: @{" InitGui " Link InitGui} @{" GuiFree " Link GuiFree} @endnode @node GuiMessage "GuiMessage function" Function prototype: short GuiMessage(void *Scr, char *text, char *title, int detail, int block, int Btext, int high, int flags) Description: Display a message to the user modally and get the user's response. This function opens a window on the specified screen. The window displays the specified message and contains one or more buttons which can be specified in the flags parameter. The return value of the function depends upon which button the user presses to respond to the message. The message is modal so the user will not be able to activate or interact with any FoxGui controls in any other windows while the message is shown. Parameters: Scr: A pointer to a FoxGui screen (or the name of a public screen) on which to display the message. text: The text of the message. The text may contain linebreak characters (specified as '\n' in C) to display multi-line messages. title: A short text string to show in the title bar of the message window. detail: The pen colour to use for the windows detail pen and for the message text. block: The pen colour to use for the windows block pen. These are equivalent to the Dpen & Bpen parameters passed to the @{" OpenGuiWindow " Link OpenGuiWindow} function. Btext: The pen colour for the text on the buttons. high: The hilight colour for the window (equivalent to the hicol parameter passed to the @{" OpenGuiWindow " Link OpenGuiWindow} function (this parameter is not currently used). flags: The flags determine the buttons shown in the window. A combination of the following flags should be used: GM_OKAY, GM_YES, GM_NO, GM_CANCEL. All buttons appear along the bottom edge of the window and are spaced such the window appears balanced. The exact location of each button will depened on how many other buttons are visible. Specifying GM_OKAY on its own will give the message window a single button labelled "Okay". This is useful for messages giving the user some information where they merely have to respond to proceed. Specifying GM_OKAY and GM_CANCEL together will give the window two buttons labelled "Okay" and "Cancel". This might be useful when the user has just told your application to erase the entire contents of your hard-disk and you want to get confirmation before proceeding. Specifying GM_YES in combination with GM_NO gives a similar effect but the buttons are labelled "Yes" and "No" instead of "Okay" and "Cancel". Specifying GM_YES, GM_NO and GM_CANCEL together will give the window three buttons labelled "Yes", "No" and "Cancel". This gives the user alternative methods of proceeding or the option not to proceed. All of the buttons have hot-keys, the hot-key being the first letter of the buttons caption in each case. Also, the Yes and Okay buttons can be activated by the return key and the No and Cancel buttons can be activated by the escape key. If the No and Cancel buttons are both present in the window then the escape key will activate the Cancel button. Returns: Returns either GM_OKAY, GM_YES, GM_NO or GM_CANCEL depending on the response selected by the user. If the function fails to open the window and display the message, it will return -1 or 0 immediately. Known bugs: None. @endnode @node Hide "Hide function" Function prototype: void Hide(void *Control); Description: Hides the specified control, removing it's imagery from the window, frame or tab control which contains it. When a control is hidden it can still be updated (for example, @{" SetEditBoxText " Link SetEditBoxText} still works when an edit box is hidden) but changes will not be seen until the control is shown again (using the @{" Show " Link Show} function). The user of your application will not be able to interact with a hidden control in any way. If a frame or tab control is hidden, any controls created within it will also be hidden. These controls will become visible again when the frame/tab control is shown unless they have been hidden independantly before or since the parent control was hidden. It is never possible to make a control visible if it is in a hidden frame or tab control. Parameters: Control: A pointer to the control to be hidden. Known bugs: Screens, windows, timers, menus, menu items and sub-menu items cannot be hidden. (Timers have no imagery so in effect they are always hidden). See also: @{" Show " Link Show} @endnode @node InitGui "InitGui function" Function prototype: short InitGui(short flags, FILE *DebugFile); Description: InitGui is one of three functions which are essential in every FoxGui program. InitGui initialises all of the internal data that the gui requires in order to work and should be called before any other FoxGui function is called otherwise crashes are not just possible but likely! InitGui also opens the Intuition and Graphics libraries and on Amigas with the IFFParse library, that is opened too so if you want to make use of any of those libraries directly from within your program you can define the library base as "extern" and then use them as normal after InitGui returns. The @{" EndGui " Link EndGui} function should be called at the end of your program and amongst other cleanup operations, it closes those three libraries. Parameters: flags: Currently, the only valid flag is FAST_MALLOCS. Whenever the FoxGui allocates memory it uses it's own memory allocation function GuiMalloc which can work in one of two ways depending on whether the FAST_MALLOCS flag was specified when InitGui was called. For more information, see the @{" GuiMalloc " Link GuiMalloc} function. DebugFile: A pointer to an open file to which to write debugging information. This is really only for my own use - masses of internal FoxGui information is written to the debug file, slowing execution down to a crawl. In the past I have used it to find tricky bugs in the Gui but now all of these have been ironed out it's practically useless. Just send NULL as this parameter. Returns: 0 for failure, or, if successful, the version of the Intuition library that FoxGui opened. If InitGui fails it's most likely to be because it failed to open a library that it requires. If InitGui fails, @{b}don't call any FoxGui functions.@{ub} Known bugs: None. See also: @{" EndGui " Link EndGui} @{" GuiLoop " Link GuiLoop} @endnode @node IntuiWindow "IntuiWindow function" Function prototype: struct Window *IntuiWindow(GuiWindow *gw); Description: This function returns a pointer to the intuition Window structure used by the specified FoxGui window. It is mainly of use when adding non-FoxGui gadgets to a FoxGui window. Parameters: gw: A pointer to the FoxGui window whose intuition Window you require a pointer to. Returns: If gw is a pointer to a FoxGui window then a pointer to the relevant intuition window is returned, otherwise NULL is returned. Known bugs: None. See also: @{" RegisterGadget " Link RegisterGadget} @{" UnRegisterGadget " Link UnRegisterGadget} @endnode @node LibVersion "LibVersion function" Function prototype: short LibVersion(void); Description: Since the @{" InitGui " Link InitGui} function opens the intuition library for you, this function allows you to find out what version of the intuition library was opened. The return value of this function will never be less than 33 since that is the minimum requirement for FoxGui. Returns: The version number of the intuition library opened by InitGui. Known bugs: None. See also: @{" InitGui " Link InitGui} @endnode @node RegisterGadget "RegisterGadget function" Function prototype: BOOL RegisterGadget(struct Gadget *gad, GuiWindow *gadwin, int (*gadfn)(struct gadget*, struct IntuiMessage *)); Description: Registers a user-created intuition gadget with FoxGui so that FoxGui can inform the user (by calling a user-defined function) whenever an intuition message is received which relates to that gadget (for example when the gadget is clicked on with the mouse). Parameters: gad: A pointer to the intuition gadget to register (note that this function can be called before or after calling the intuition function AddGadget to add the gadget to the window's gadget list). gadwin: A pointer to the FoxGui window which contains (or is about to contain) the gadget. If the gadget is created in a non-FoxGui window then this parameter should be NULL. gadfn: A pointer to the function to call whenever the gadget gets an intuition message (an IntuiMessage). The prototype should be as follows: int MyFunction(struct Gadget *gad, struct IntuiMessage *message) When the function is called it will be passed a pointer to the gadget to which the IntuiMessage refers and a pointer to the IntuiMessage itself (note that this is a pointer to the actual IntuiMessage that intuition sent to FoxGui so it is important that you don't modify it in any way). It is your responsibility to reply to the message (with the intuition function ReplyMsg) when you have finished with it - FoxGui doesn't do this for you. Your function should return either @{" GUI_CONTINUE or GUI_END " Link GuiContinueEnd}. Returns: TRUE if successful, FALSE otherwise. Known bugs: None. See also: @{" IntuiWindow " Link IntuiWindow} @{" UnRegisterGadget " Link UnRegisterGadget} @endnode @node RestoreEveryStatus "RestoreEveryStatus function" Function prototype: void RestoreEveryStatus(BOOL redraw); Description: This function restores the enabled/disabled status of every pushbutton, edit box and drop-down list box in the application to the state it was when the function @{" StoreEveryStatus " Link StoreEveryStatus} was last called. If StoreEveryStatus has not previously been called or if this function has been called already since the last call to StoreEveryStatus then this function will do nothing. Note that this function does not currently affect menus, list boxes, radio buttons or tick boxes. Parameters: redraw: If TRUE then all of the affected controls will be redrawn to reflect their new status. Known bugs: None. See also: @{" DisableEverything " Link DisableEverything} @{" EnableEverything " Link EnableEverything} @{" StoreEveryStatus " Link StoreEveryStatus} @endnode @node SetDelay "SetDelay function" Function prototype: void SetDelay(int time); Description: When the user clicks on a pushbutton which was created with the BN_AR flag (so that the button will be triggered continually while it is held down), the button will be triggered immediately and then there will be a DELAY before it is next triggered, after which there will be a regular PERIOD between subsequent triggers. This function sets that initial delay. Parameters: time: The time (in milliseconds) to delay after the initial triggering of auto-repeating pushbuttons before triggering again. Known bugs: None. See also: @{" SetPeriod " Link SetPeriod} @endnode @node SetGuiPens "SetGuiPens function" Function prototype: void SetGuiPens(short hipen, short lopen); Description: Sets the pen colours used by FoxGui to render 3D borders. The Gui uses two colours - one bright and one dark to make the objects appear as though light were being shone across the screen from a light source at the top left. Hence, objects which stand out from the screen will have a bright top left hand corner and a dark (shaddowed) bottom right corner. Objects which appear pressed into the screen will have a shaddowed top left corner and a bright bottom right corner. Parameters: hipen: A bright colour used to draw well lit edges (1 by default). lopen: A dark colour used to draw shaddowed edges (2 by default). The default values shown are used if this function is not called by your application. Known bugs: None. @endnode @node SetGuiPensFromPubScreen "SetGuiPensFromPubScreen function" Function prototype: BOOL SetGuiPensFromPubScreen(char *pub_screen_name); Description: Like the @{" SetGuiPens " Link SetGuiPens} function, this function sets the pen colours used by FoxGui to render 3D borders. Unlike SetGuiPens where you pass the pen colours to use, this function takes the name of a public screen as a parameter and sets the Gui pens to the same values as used by the public screen named. This function only works on Amigas which support public screens. This function is particularly useful for picking up the pen colours from the workbench screen (the public name of the workbench screen is "Workbench"). This ensures that whatever the users system colours are, the FoxGui gadgets will appear in the same colours and hence in 3D. Parameters: pub_screen_name: The name of the public screen whose pens are to be copied (public screen names are case sensitive). Returns: TRUE if successful, FALSE otherwise. Known bugs: None. @endnode @node SetPeriod "SetPeriod function" Function prototype: void SetPeriod(int time); Description: When the user clicks on a pushbutton which was created with the BN_AR flag (so that the button will be triggered continually while it is held down), the button will be triggered immediately and then there will be a DELAY before it is next triggered, after which there will be a regular PERIOD between subsequent triggers. This function sets that period. Parameters: time: The time (in milliseconds) to delay between each triggering of the auto-repeating pushbutton. Known bugs: None. See also: @{" SetDelay " Link SetDelay} @endnode @node Show "Show function" Function prototype: void Show(void *Control); Description: Shows the specified hidden control. Controls are automatically shown when they are first created so this function is only used to show controls which have subsequently been hidden using the @{" Hide " Link Hide} function. If a frame which contains other controls is shown then any controls contained within the frame will also be shown unless they themselves have been hidden either before or after the frame was hidden. The same is true for tab controls. For example, calling Show for a hidden control in a hidden frame won't cause the control to be shown immediately because the parent frame is still hidden but if the parent frame is now shown (using the Show function again) then the frame and the control will become visible. Parameters: Control: A pointer to the hidden control to show. Known bugs: Screens, windows, timers, menus, menu items and sub-menu items cannot be hidden (and hence shown). (Timers have no imagery so in effect they are always hidden). See also: @{" Hide " Link Hide} @endnode @node StoreEveryStatus "StoreEveryStatus function" Function prototype: void StoreEveryStatus(void); Description: Stores the status (enabled or disabled) of every FoxGui pushbutton, edit box and drop-down list box in the application so that this status can be restored at some future point by calling the @{" RestoreEveryStatus " Link RestoreEveryStatus} function. Note that this function does not affect menus, list boxes, radio buttons or tick boxes. Known bugs: None. See also: @{" DisableEverything " Link DisableEverything} @{" EnableEverything " Link EnableEverything} @{" RestoreEveryStatus " Link RestoreEveryStatus} @endnode @node UnRegisterGadget "UnRegisterGadget function" Function prototype: BOOL UnRegisterGadget(struct Gadget *gad); Description: Removes a user-defined gadget from FoxGui's registry. This function should only be used with gadgets that have previously been registered using the @{" RegisterGadget " Link RegisterGadget} function. You should always remove a gadget from FoxGui's registry when you destroy it. Parameters: gad: A pointer to the intuition gadget to remove from the registry. Returns: TRUE if successful, FALSE otherwise. Known bugs: None. See also: @{" RegisterGadget " Link RegisterGadget} @endnode @node GuiFree "GuiFree macro" Macro prototype: void GuiFree(void *p) Macro definition: #define GuiFree(p) GuiFreeMem(p,__LINE__,__FILE__) Description: This function is used to free memory allocated with the GuiMalloc function. It can work in one of two ways depending upon whether the FAST_MALLOCS flag was specified when InitGui was called. If FAST_MALLOCS has not been specified then GuiFree will detect any attempt to free memory that wasn't allocated by GuiMalloc or which has become corrupted due to some form of memory scribble. See the @{" InitGui " Link InitGui} and @{" GuiMalloc " Link GuiMalloc} functions for more details. Parameters: p: A pointer to a section of memory allocated with the GuiMalloc function. See also: @{" GuiMalloc " Link GuiMalloc} @{" InitGui " Link InitGui} @{" Warnings on the use of macros " Link MacroWarnings} @endnode @node ProtoList "FoxGui function prototypes" @{b}List Boxes@{ub} void SortListBox(ListBox *p, int flags, int startnum, BOOL refresh); void ClearListBoxTabStops(ListBox *nlb, BOOL refresh); BOOL SetListBoxTabStops(ListBox *nlb, BOOL refresh, short num, ...); void SetListBoxTopNum(ListBox *lb, int num, BOOL refresh); void SetListBoxHiNum(ListBox *lb, int num, BOOL refresh); int NoTitles(ListBox *lb); int NoLines(ListBox *lb); int TopNum(ListBox *lb); int HiNum(ListBox *lb); ListBoxItem *HiElem(ListBox *lb); char *HiText(ListBox *lb); BOOL AddListBoxTitle(ListBox *nlb, char *title, int frontpen, BOOL refresh); ListBoxItem *AddListBoxItem(ListBox *nlb, char *item, BOOL refresh); void ListBoxRefresh(ListBox *lb); void ClearListBoxTitles(ListBox *lb, BOOL refresh); void ClearListBoxItems(ListBox *lb, BOOL refresh); BOOL DisableListBox(ListBox *lb); void DisableAllListBoxes(void); void DisableWinListBoxes(GuiWindow *w); BOOL EnableListBox(ListBox *lb); void EnableAllListBoxes(void); void EnableWinListBoxes(GuiWindow *w); BOOL DestroyListBox(ListBox *nlb, BOOL refresh); void DestroyAllListBoxes(BOOL refresh); void DestroyWinListBoxes(GuiWindow *w, BOOL refresh); ListBox* FOXLIB MakeListBox(void *Parent, int left, int top, int width, int height, int lborder, int tborder, int frontpen, struct TextAttr *font, int (*selfn) (ListBox*), int flags, ...) @{b}Drop Down List Boxes@{ub} void StoreDDListBoxStatus(void); void RestoreDDListBoxStatus(BOOL redraw); void ClearDDListBox(DDListBox *l); BOOL RemoveFromDDListBox(DDListBox *list, char *str); BOOL AddToDDListBox(DDListBox *list, char *str); void SortDDListBox(DDListBox *p, int flags); BOOL SetDDListBoxPopup(DDListBox *l, int x, int y, int width, int height); BOOL AssociateDDListBox(DDListBox *l, DDListBox *m); DDListBox *MakeSubDDListBox(DDListBox *lb, char *string, int left, int top, int width, int height, int id, BOOL (*callfn)(DDListBox*)); void EnableDDListBox(DDListBox *p, BOOL redraw); void DisableDDListBox(DDListBox *p, BOOL redraw); void EnableAllDDListBoxes(BOOL redraw); void DisableAllDDListBoxes(BOOL redraw); void EnableWinDDListBoxes(GuiWindow *c, BOOL redraw); void DisableWinDDListBoxes(GuiWindow *c, BOOL redraw); void DestroyDDListBox(DDListBox *p, BOOL refresh); void DestroyAllDDListBoxes(BOOL refresh); void DestroyWinDDListBoxes(GuiWindow *c, BOOL refresh); DDListBox *MakeDDListBox(void *Parent, int x, int y, int len, int buflen, int MaxHeight, int BorderCol, int Bcol, int Tcol, int id, char *prestr, char *poststr, short (*callfn) (DDListBox*), long flags); int GetDDListBoxID(DDListBox *l) char *GetDDListBoxText(DDListBox *l) BOOL SetDDListBoxText(DDListBox *l, char *c) @{b}Edit Boxes@{ub} void StoreEditBoxStatus(void); void RestoreEditBoxStatus(BOOL redraw); void RefreshEditBox(EditBox *p); BOOL SetEditBoxFocus(EditBox *p); BOOL SetEditBoxCols(EditBox *p, int BorderCol, int Bcol, int Tcol); char *GetEditBoxText(EditBox *p); int GetEditBoxInt(EditBox *p); float GetEditBoxFloat(EditBox *p); BOOL SetEditBoxText(EditBox *p, char *text); BOOL SetEditBoxInt(EditBox *p, int num); BOOL SetEditBoxFloat(EditBox *p, float num); BOOL SetEditBoxDP(EditBox *p, int num); void EnableEditBox(EditBox *p, BOOL redraw); void DisableEditBox(EditBox *p, BOOL redraw); void EnableAllEditBoxes(BOOL redraw); void DisableAllEditBoxes(BOOL redraw); void EnableWinEditBoxes(GuiWindow *c, BOOL redraw); void DisableWinEditBoxes(GuiWindow *c, BOOL redraw); void DestroyEditBox(EditBox *p, BOOL refresh); void DestroyAllEditBoxes(BOOL refresh); void DestroyWinEditBoxes(GuiWindow *c, BOOL refresh); EditBox *MakeEditBox(void *Parent, int x, int y, int len, int buflen, int BorderCol, int Bcol, int Tcol, int id, char *prestr, char *poststr, BOOL (*callfn) (EditBox*), long flags); int GetEditBoxID(EditBox *p) @{b}Menus@{ub} BOOL DisableWinMenus(GuiWindow *win); BOOL EnableWinMenus(GuiWindow *win); BOOL DisableMenu(GuiWindow *win, struct Menu *menu); BOOL EnableMenu(GuiWindow *win, struct Menu *menu); BOOL DisableMenuItem(GuiWindow *win, struct MenuItem *item); BOOL EnableMenuItem(GuiWindow *win, struct MenuItem *item); void SetWinMenuFn(GuiWindow *win, int (*fn) (GuiWindow*, struct MenuItem*)); void ClearMenus(GuiWindow *win); void ShareMenus(GuiWindow *dest, GuiWindow *source); struct Menu *AddMenu(GuiWindow *win, char *name, int leftedge, int enabled); struct MenuItem *AddMenuItem(GuiWindow *win, struct Menu *menu, char *name, char *selname, unsigned short flags, int key, int enabled, int checkit, int checked, int menutoggle); struct MenuItem *AddSubMenuItem(GuiWindow *win, struct MenuItem *menuitem, char *name, char *selname, unsigned short flags, int key, int enabled, int checkit, int checked, int menutoggle); BOOL RemoveMenuItem(GuiWindow *win, struct MenuItem *item); @{b}Windows@{ub} BOOL SleepPointer(GuiWindow *win); void WakePointer(GuiWindow *win); void CloseGuiWindow(GuiWindow *w); GuiWindow *OpenGuiWindow(void *Scr, int Left, int Top, int Width, int Height, int minwidth, int minheight, int Dpen, int Bpen, int HiCol, char *Title, int flags, int (*CloseFn)(GuiWindow *), ...); void CloseAllWindows(void); void CloseScrWindows(GuiScreen *sc); BOOL ShowFileRequester(GuiWindow *Wnd, char *path, char *pattern, char *title, BOOL Save, int (*callfn) (char*, char*), int Col_GW1, int Col_GW2, int Col_GW3, int Col_OB1, int Col_OB2, int Col_EB1, int Col_EB2, int Col_EB3, int Col_B1); void SetFName(char *fname); void SetPath(char *path); void UpdateFList(void); void WinBlankToEOL(GuiWindow *w) void WinClear(GuiWindow *w) void WinHideCursor(GuiWindow *w) void WinHome(GuiWindow *w) void WinPrint(GuiWindow *w, char *str) void WinPrintCol(GuiWindow *w, char *str, int col) void WinPrintHi(GuiWindow *w, char *str) void WinPrintTab(GuiWindow *w, int x, int y, char *str) void WinShowCursor(GuiWindow *w) void WinTab(GuiWindow *w, int x, int y) void WinWrapOff(GuiWindow *w) void WinWrapOn(GuiWindow *w) @{b}Miscelaneous@{ub} void CheckMessages(void); short InitGui(short flags, FILE *DebugFile); void GuiLoop(void); void EndGui(void); short LibVersion(void); void SetGuiPens(short hipen, short lopen); BOOL SetGuiPensFromPubScreen(char *pub_screen_name); BOOL ShowMessage(GuiScreen *scr, char *a, char *b, char *c, int col); BOOL DestroyMessage(void); void SetPeriod(int time); void SetDelay(int time); void *GuiMalloc(unsigned NoOfBytes, unsigned long flags); BOOL WasGuiMallocd(void *p); void GuiFreeMem(void *p, int line, char *fname); void StoreEveryStatus(void); void RestoreEveryStatus(BOOL redraw); void EnableEverything(int redraw); void DisableEverything(int redraw); void DrawLines(GuiWindow *win, short *points, int count, int col); short GuiMessage(void *Scr, char *text, char *title, int detail, int block, int Btext, int high, int flags); void Hide(void *Control); void Show(void *Control); void DisableControl(void *Control, BOOL refresh); void EnableControl(void *Control, BOOL refresh); void Destroy(void *Control, BOOL refresh); GuiWindow *GetWindow(void *Control); BOOL RegisterGadget(struct Gadget *gad, GuiWindow *gadwin, int (*gadfn)(struct gadget*, struct IntuiMessage *)); BOOL UnRegisterGadget(struct Gadget *gad); struct Window *IntuiWindow(GuiWindow *gw); void GuiFree(void *p) @{b}Screens@{ub} BOOL CloseGuiScreen(GuiScreen *scr); void CloseAllGuiScreens(void); GuiScreen *OpenGuiScreen(int Depth, int DPen, int BPen, struct TextAttr *Font, char *Title, int (*LastWinFn)(GuiScreen *), int flags, ...); @{b}Buttons@{ub} void StoreButtonStatus(void); void RestoreButtonStatus(void); void DisableButton(PushButton *Bptr); void DisableAllButtons(void); void DisableWinButtons(GuiWindow *w); void EnableButton(PushButton *Bptr); void EnableAllButtons(void); void EnableWinButtons(GuiWindow *w); void DestroyButton(PushButton *b, BOOL refresh); void DestroyAllButtons(BOOL refresh); void DestroyWinButtons(GuiWindow *w, BOOL refresh); PushButton *MakeButton(void *Parent, char *name, int left, int top, int width, int height, int tcol, int bcol, int key, struct Border *cb, int (*callfn) (PushButton*), short flags); @{b}Output Boxes@{ub} void SetOutputBoxDP(OutputBox *p, int dp); void SetOutputBoxInt(OutputBox *p, int num); void SetOutputBoxFloat(OutputBox *p, float num); void SetOutputBoxText(OutputBox *p, char *text); void DestroyOutputBox(OutputBox *p, BOOL refresh); void DestroyAllOutputBoxes(BOOL refresh); void DestroyWinOutputBoxes(GuiWindow *c, BOOL refresh); void SetOutputBoxCols(OutputBox *ob, int Bcol, int Tcol, BOOL refresh); OutputBox *MakeOutputBox(void *Parent, int x, int y, int width, int len, int Bcol, int Tcol, int id, char *prestr, char *poststr, struct TextAttr *font, long flags); int GetOutputBoxID(OutputBox *o) @{b}Boolean Gadgets@{ub} RadioButton *ActiveRadioButton(RadioButton *rb); void DestroyRadioButton(RadioButton *rb, BOOL refresh); RadioButton *MakeRadioButton(void *Parent, RadioButton *MutEx, int left, int top, int width, int height, int fillcol, char *caption, struct TextAttr *font, int captioncol, int (*callfn) (RadioButton*), int flags); BOOL TickBoxValue(TickBox *tb); void DestroyAllRadioButtons(BOOL refresh); void DestroyAllTickBoxes(BOOL refresh); void DestroyTickBox(TickBox *tb, BOOL refresh); void DestroyWinRadioButtons(GuiWindow *gw, BOOL refresh); void DestroyWinTickBoxes(GuiWindow *gw, BOOL refresh); void DisableRadioButton(RadioButton *rb); void DisableTickBox(TickBox *tb); void EnableRadioButton(RadioButton *rb); void EnableTickBox(TickBox *tb); TickBox *MakeTickBox(void *Parent, int left, int top, int width, int height, int tickcol, int fillcol, char *caption, struct TextAttr *font, int captioncol, int (*callfn) (TickBox*), int flags); @{b}Timers@{ub} BOOL DestroyTimer(Timer *t); void DestroyAllTimers(void); Timer *MakeTimer(short flags, int (*CallFn) (Timer *, long)); void StartTimer(Timer *t); void StopTimer(Timer *t); void PauseTimer(Timer *t); void UnpauseTimer(Timer *t); void AddTime(Timer *t, long secs); void SetTime(Timer *t, long secs); @{b}Frames@{ub} void DestroyAllFrames(BOOL refresh); void DestroyFrame(Frame *Fptr, BOOL refresh); void DestroyWinFrames(GuiWindow *w, BOOL refresh); Frame *MakeFrame(void *Parent, char *name, int left, int top, int width, int height, int tcol, int bcol, struct Border *cb, int (*callfn) (Frame*, short, short, short, void**), short flags, ...); @{b}Images@{ub} GuiBitMap *LoadBitMap(char *fname); BitMapInstance *ShowBitMap(GuiBitMap *bm, GuiWindow *w, unsigned short x, unsigned short y, short flags); BOOL HideBitMap(BitMapInstance *bmi); BOOL FreeGuiBitMap(GuiBitMap *bm); GuiBitMap *ScaleBitMap(GuiBitMap *source, unsigned short destwidth, unsigned short destheight); BOOL RedrawBitMap(BitMapInstance *bmi); BOOL AttachBitMapToControl(GuiBitMap *bm, void *control, short left, short top, short width, short height, int flags); BOOL ScreenColoursFromILBM(GuiScreen *sc, char *fname); @{b}Progress Bars@{ub} void DestroyProgressBar(ProgressBar *pb, BOOL refresh); ProgressBar *MakeProgressBar(void *Parent, int left, int top, int width, int height, short fillcol, int tcol, short flags); void SetProgress(ProgressBar *pb, int progress); void SetProgressMax(ProgressBar *pb, int progressmax); @{b}Tab controls@{ub} TabControl *MakeTabControl(void *Parent, int left, int top, int width, int height, int tcol, int fcol, int tabheight, short flags, int numtabs, ...); void DestroyTabControl(TabControl *tc, BOOL refresh); void DestroyWinTabControls(GuiWindow *w, BOOL refresh); void DestroyAllTabControls(BOOL refresh); Frame *TabControlFrame(TabControl *tc, int frameno); void EnableTabControl(TabControl *tc); void DisableTabControl(TabControl *tc); @endnode @node MacroWarnings "Warnings and notes on the use of macros" A small number of FoxGui functions (listed below) are currently defined as macros rather than real functions. This means that when you call the macro, the actual text of the macro gets substituted into your code by the preprocessor rather than a link to the function being made at link time. Although you can use macros exactly as you would use functions there are a number of things you should bear in mind when doing so :- Most compilers perform macro substitution on the first parse of your source code which means that if there is an error on the line with the macro on it and the compiler shows you the line with the error it won't look the way it did when you typed the line in and may make error spotting more difficult. To help you when this happens, definitions of all of the FoxGui macros are included on their pages in this document. It is not guaranteed that all FoxGui macros will exist in their current form in later releases of the Gui. This doesn't mean that you shouldn't use them. There are two things that may cause a macro to change. The macro may be removed and implemented as a function or the underlying Gui structures may change necessitating a change in the macro definition. In either case the prototype will remain the same so there will be no need for you to change your code - you will just need to recompile it. You should never be tempted to manually expand the macros. For example, the macro GetEditBoxID(p) is currently defined as (p)->id. Don't be tempted to use (p)->id in your functions. Always use GetEditBoxId(p). In this way you will ensure that your code will not have to be changed for future releases of FoxGui where the macro implementation may be different. The following FoxGui functions are currently implemented as macros :- @{ " GetEditBoxID " Link GetEditBoxID} @{ " GetDDListBoxID " Link GetDDListBoxID} @{ " GetDDListBoxText " Link GetDDListBoxText} @{ " GetOutputBoxID " Link GetOutputBoxID} @{ " GuiFree " Link GuiFree} @{ " SetDDListBoxText " Link SetDDListBoxText} @{ " WinBlankToEOL " Link WinBlankToEOL} @{ " WinClear " Link WinClear} @{ " WinHideCursor " Link WinHideCursor} @{ " WinHome " Link WinHome} @{ " WinPrint " Link WinPrint} @{ " WinPrintCol " Link WinPrintCol} @{ " WinPrintHi " Link WinPrintHi} @{ " WinPrintTab " Link WinPrintTab} @{ " WinShowCursor " Link WinShowCursor} @{ " WinTab " Link WinTab} @{ " WinWrapOff " Link WinWrapOff} @{ " WinWrapOn " Link WinWrapOn} @endnode @node GuiContinueEnd "The GUI_END and GUI_CONTINUE flags" Most user defined callback functions (functions supplied by the user that FoxGui calls when certain events occur) have to return either GUI_END or GUI_CONTINUE. GUI_CONTINUE instructs FoxGui to continue processing events. GUI_END causes event processing for this process to stop and the function @{" GuiLoop " Link GuiLoop} to return. @endnode @node S_AUTO_SIZE "The S_AUTO_SIZE flag" The S_AUTO_SIZE flag can be specified for all visible FoxGui controls except windows and screens. If any control has the S_AUTO_SIZE flag set and the window has a size gadget then resizing the window will cause the control to be resized and positioned so that it's size and position relative to the window remain the same. See also: @{" OpenGuiWindow " Link OpenGuiWindow} @{" MakeProgressBar " Link MakeProgressBar} @{" MakeFrame " Link MakeFrame} @{" MakeButton " Link MakeButton} @{" MakeRadioButton " Link MakeRadioButton} @{" MakeTickBox " Link MakeTickBox} @{" MakeEditBox " Link MakeEditBox} @{" MakeListBox " Link MakeListBox} @{" MakeDDListBox " Link MakeDDListBox} @{" MakeOutputBox " Link MakeOutputBox} @{" MakeTabControl " Link MakeTabControl} @endnode @node WhatsNew42 "What's new in release 4.2?" @{b}New features in release 4.2@{ub} * Drag/Drop functionality has been added to windows, frames and listboxes. To accomodate these changes, various function prototypes have changed slightly including the functions MakeFrame, MakeListBox and OpenGuiWindow. * A double click-event is now available for list boxes. You can now specify a function to call if the user double-clicks on an item in a list box control. * Other improvements to list boxes: They automatically get a vertical scroller when more items are added than can be shown in the list and they automatically get a horizontal scroller when items are added which are too long to be shown in full. @{b}Bug fixes in release 4.2@{ub} * If a frame was created without specifying the FM_LBUT flag then right mouse-button clicks on the frame would not be detected and the frame's title (if it had one) would appear above and to the left of the frame instead of in the centre. This is now fixed. @endnode @node WhatsNew41 "What's new in release 4.1?" @{b}New features in release 4.1@{ub} * Added the function SetGuiPensFromPubScreen which sets the gui pens to the values used by a specified public screen. * Tab controls now have rounded corners. @{b}Bug fixes in release 4.1@{ub} * The "far" directive in foxconsole.h has been replaced with "__far" for ANSI compliance. * A bug in the way that drop-down list boxes were destroyed and which could have caused the machine to crash if the list box had a child or if the list box was associated has been fixed. * The descriptions of the parameters detail and Btext were incorrect for the function GuiMessage as described in this documentation. This has been corrected. @endnode @node WhatsNew4 "What's new in release 4.0?" @{b}New features in release 4.0@{ub} * Recompiled all of the code with SAS/C 6.51. The code now requires sc.lib and scm.lib to be linked with it rather than the old lc.lib and lcm.lib which weren't compatible with newer versions of the compiler. This should allow far more people to make use of FoxGui. * The ability to add your own intuition gadgets to FoxGui windows or to your own windows within a FoxGui program. @{b}Bug fixes in release 4.0@{ub} * If the cursor keys were used to scroll list boxes then hidden scrollable list boxes would also be redrawn. This is now fixed. * If two listboxes in different frames of the same tab control overlapped then it was impossible to select items in one of the list boxes by clicking in the overlapping region. This is now fixed. * It is no-longer possible for buttons in GuiMessage windows to overlap. @endnode @node WhatsNew3 "What's new in release 3.0?" @{b}New features in release 3.0@{ub} * Tab controls. * Timer controls. * All controls can be hidden and shown. * Custom borders in buttons and frames are now resized when the button or frame resizes. * Frames and tab controls can now be used as holders for other controls. * The parameter list for the function SetOutputBoxCols has changed slightly. * The way that list boxes work has been slightly improved. * New flags have been added to create clear edit boxes and drop-down list boxes. * A whole new set of generic functions which work on any control type have been added. The functions are: Hide, Show, DisableControl, EnableControl, Destroy and GetWindow. * A new function RemoveMenuItem has been added. * Enhancements have been made to the GuiMessage function. @{b}Bug fixes in release 3.0@{ub} * The function TickBoxValue always returned FALSE no matter what the actual value was. This has been fixed. @endnode @node WhatsNew2 "What's new in release 2.0?" @{b}New features in release 2.0@{ub} * Much better screen support (Interlace, new screen modes etc). * Windows can be resized. * All controls are capable of stretching, shrinking and moving to fit the new bounds of resized windows. * ILBM images can be loaded, drawn on windows and attached to buttons and frames (either clipped or scaled to fit exactly). * Tick boxes can be clear. * Pop-up list boxes and sub drop-down list boxes can be made to calculate the necessary width for you so that you don't have to work it out yourself. This is useful if you don't know what font will be in use. @{b}Bug fixes in release 2.0@{ub} * Text in frames, buttons and output boxes is now clipped to fit. Previously it would often overflow out of the control. If the control is resized (due to a window resizing) then the caption is reclipped. * On an A500, if a long item was selected in a drop-down list box, selecting another, shorter item would sometimes leave the last character of the previous text behind. This is now fixed. * If you don't want a caption in a button or frame you can now pass NULL for the name parameter. Previously you had to use an empty string (""). * The SetEditBoxFocus() function used to fail if another string gadget (i.e. another edit box or drop-down list box) was active. This is now fixed. * There were various bugs associated with font handling which are now fixed. @endnode @node MacroTemplate "... macro" Macro prototype: Macro definition: Description: Parameters: Returns: See also: @{" Warnings on the use of macros " Link MacroWarnings} @endnode @node FunctionTemplate "... function" Function prototype: Description: Parameters: Returns: Known bugs: None. See also: @endnode