Extra Docs for Clarion GUI - by: Paul M. Blais, St. Paul, MN CIS [72103,111] August 23, 1993 rev. October 19, 1993 version 3005 additions DISCLAIMER! - I am not now nor have I ever been associated with Clarion Software Corp. This information is provided as is for use by Clarion CDD 3.0 users and may be distributed freely. The following is not necessarily complete and may have minor inaccuracies. Some of the information has been gathered from CDD forum threads and I would like to thank those of you that contributed. I would greatly appreciate any errors or omissions you find be sent to me via the Clarion CDD3 forum 8. I'll take any comments and add them to this list as I have time. I will resend the file to the Clarion Lib when I have made updates a post a message in forum section 8 CDD Support. Enough people downloaded the first release so I'll continue to add more stuff as I find it. The GUI environment as shipped by Clarion3 version 3004 updated in version 3005 has many amazing features. It is unfortunate that the documentation was so meager. I started keeping some notes for myself so I could use GUI. I personally think GUI is great and I hope you can get something out of these notes to help you like it too. GUI is made up of the following elements that are different from normal CDD. Screens / Screen Borders Buttons Icons Fields List Boxes Radio Buttons Colors Special Features Each of these function just a little bit different than the way you may be used to. In general, GUI does more for you automatically. I'm sure many people will want Clarion to enhance the GUI to allow more control. I'm not sure it is required. The look of the tool is clearly based on MOTIF / XWindows. If we ask for too many features I think it could hurt the product. Before you get too frustrated, plan your colors and screens to take advantage of how the product functions. When you do, I think you get a very nice looking screen that is not cluttered with lots of colors. The subtle 3D effect looks best without too many colors. Don't fight the system. Many features of standard CDD cannot be used in GUI. Most of all these unused features tend to have no effect rather than a bad effect. You can bang your brains out carefully defining "hot key colors", only to find out GUI won't use them. This may be OK since later on you may want to distribute the app without GUI turned on, so be aware of the limitations contained in these notes. There are a few cases that produce strange results but I have not found anything that will crash the GUI that wouldn't crash standard Clarion. SCREENS / SCREEN BORDERS ======================== GUI screens are slightly different than standard VGA screens. For a full size screen they are 80 columns wide by 30 rows not the normal 25 rows. Before you go crazy with the extra rows, be aware of the following limitations, where Y is the number of rows and X is the number of columns in your screen. To my knowledge GUI does not support Virtual screens (I've never tried). 1. Row 1 is for titles, avoid variables since they will display funny, only use string literals (what you can type). 2. Row 2 & Y are dead, do not use them 3. Columns 1, 2, (X-1), and X are also dead 4. Columns 3 & (X-2) are also dead for row 1 only. All these above areas are not really dead, they just will be used by GUI and anything you put there won't be visible or may appear funny. These extra rows are used to make the GUI screen borders. Do not put any tracking characters, they don't work in GUI (but they won't hurt). By the way screen shadows (or any other kind of shadows) have no effect. They won't help nor will they hurt. GUI borders are created based on the foreground color of the screen edges. This means a Blue on White window gets a Blue border and a White window. All borders are the same color. The top border gets extra wide, therefore you must not use row two of the screen. Please note that the Clarion.app file will not generate proper GUI screens unless you take several extra steps. Like removing all the tracking characters from the borders and moving the message line down to row 3 or 4. You may need to adjust any scroll boxes away from the edges too. I had planned to redo the Clarion App screens to make this easier for GUI, but I hear 3005 will add changes so, I wouldn't do it just yet. Screen title generation is also done automatically based on any literal text you type on row one. The position is not automatically centered, so where you put it is where it will go. Do not use the first or last three columns on row one since they are eaten up by the border. The color of the text is based on the color you "paint" it in the appgen screen formatter. For example I like a BLUE on WHITE windows with a BRIGHT on BLUE title. The result is BLUE borders, WHITE windows, and BRIGHT on BLUE title. It appears that only the background color is used to determine title text color. I always paint the text with both so I can better visualize the screen while in appgen. GUI docs recommend painting the whole line, but only the actual text needs to be done. If you mix and match the coloring you get NO TITLE! One title one color, thank you very much. BUTTONS ======= GUI buttons may just be my favorite feature. There are several considerations that you must use to create buttons. Create buttons as you normally do in the screen formatter, but remember to: 1. Forget about button shadows - they won't. Clarion says they will mess up. I find they do nothing. 2. Only worry about the "Normal" color, all others are ignored. The button will be the color you define. 3. For all buttons with a text label more than one character the following apply. a. Buttons are one space wider horizontally in each direction than they appear in the formatter. b. Buttons take one half row above the button text and one half row below for EACH line of text IE. They may NOT be stacked vertically. The following is either a bug or a feature. Rows In Rows Above Rows Below Total Button Button Button Rows 1 1\2 1\2 2 2 1\2 1 3 1\2 3 1\2 1 1\2 5 4 1\2 2 6 1\2 This is a bug! Further more the "extra" room allocated below the text in unpickable. If you use your mouse to press the button in the region greater than one half line, you cannot "press" the button. (I have not checked this out in 3005) Buttons may be taller than one row by adding a | vertical bar symbol in the button string. When no characters follow the vertical bar nothing will happen. c. Hot alt key characters will be displayed with an underscore located under the character that is preceeded with an & anpersand. If you do use a Normal Hot color in the formatter you will be able to see the hot key marked in the formatter. This will help you keep track of the hot keys. The hot key color will NOT be used by GUI however. 4. Single character buttons take only one row and three spaces wide. These may be stacked vertically adjacent unlike buttons with more than one character. 5. When prompted in the screen formatter for the button text you may also use a variable name instead. I use this to make single down arrow buttons. I define a global variable called dn to hold the ascii character for a down arrow. Then in the screen formatter at the prompt for button text I enter dn without quotes. It appears in the formatter as an @ and therfore takes only one column of space. The screen then appears more like it will at run time. If you screw up in defining a button the good news is the application will still run, but the screen will look poor. Disabled buttons in GUI are handled automatically. When a Button is disabled, the button text will revert to a recessed low contrasting color. You are just able to read the text if you look close. The normal color restores as soon as the button is enabled. Again all this is based only on the "normal" display color - you can not override it! ICONS ===== The GUI docs contain a whole one half page about using pcx & gif files for icons. Mike Dufort @ Clarion has placed a good discussion on PCX files in the forum lib. This is good stuff so I won't say any more. FIELDS ====== Data fields in GUI are really something. All input enabled fields will be recesssed into the screen showing the maximum number of positions permitted. Memo fields too! When you stack the input fields vertically you get a narrow line between each field vertically. All the standard color rules apply just the same as standard CDD. Prompts are treated similar to Buttons. Hot Key colors are not used and selected colors do not work either. Hot key designation must be done with the ampersand character in appgen. This will cause the hot key character to be displayed with an underscore. You may not like it a well, but this is pretty MOTIF standard stuff. If you have to have all the multicolored prompts then do them as Text for the entire app. Disabled fields are recessed into the screen and take on a color almost like the foreground. They look dim but a still readable. This is all based on the normal color of the text. To get this effect you don't have to do anything. There is a bug in memo fields. Memos will disable in GUI, but they won't look like it. It really helps to line up the input fields to make the screen look clean. I have always felt this way, but GUI needs it a little more. Memo fields require one half line above & below and one extra column left and right. Do not place things right next to or above memo fields. If you do the characters may get chopped off. LIST BOXES ========== List boxes are a little nicer in GUI. They really start to look like Windows. The scroll bars are better looking and you get an "elevator button" just like in Windows. The scroll bars do eat up a little more room. List boxes are displayed recessed into the window. You might choose to use a different color than your normal screen. The selector bar is defined based on the color of the window. You do not have control of the color. The bar will display the same color as the scroll box, The 3d effect will make the selected line appear raised above the list. It is a very nice effect. Please leave at least one column left and right as well as one line above and below your list boxes. In the screen formatter the Vertical Scroll bar will only take one column. In GUI it will take two. The extra column will come out of the tabel. If you use vertical scroll bars make the list box one more column wide than you really need. Note that 3005 has a bug with horizontal scroll bars - they don't! If you use the VIEW template in GUI, be sure to resize the window and expand the screen area to 30 rows if you want a full screen. In 3005 the speed issue is of less concern. Clarion docs recommend keeping the size of the list box small to keep the speed up. Under release 3004, the speed is not real great. Release 3005 IS faster. RADIO BUTTONS ============= Radio Buttons are pretty simple in GUI. You can specify colors just like you can in text mode CDD. The buttons look great. An unselected choice looks like a raised button the same color and the screen. A selected choice appears as a recessed button, with a black dot in the center. It would appear that black screens will not look good for radio buttons. COLORS ====== GUI colors work different than normal. This I think is due to the 3D effect that is being created. Based on a simple foreground & background color, GUI creates two more colors to simulate the 3D look. It can not create the colors on its own so it must rely on the existing color pallete. That 3D Look The most appealing thing about GUI is that 3D look you get on windows, buttons and fields. While not quite as nice MOTIF or XWindows, it is about as close as I think you can get. To do this little graphic illusion you need to understand how the colors are used to create the effect. Along the inside and outside edges of almost everything you will see the use of thick and thin tracking lines. These lines are colored based on the color of the element. Colors that are slightly lighter and slightly darker are combined with black to make all the magic work right. The 3D look attempts to simulate a light source located above and to the left of your monitor. Text is generally flat, unless disabled, when it is recessed and changed to the screen color. I heard discussions in the forum requesting this to be changed. Some users have a hard time reading the screen. I'ld vote for a change, but if you have an opinion let them know by leaving a suggestion. Borders are raised above the window. Buttons are raised, but recess when SELECT() is called and the button text also recesses. Disabled button text recesses into the button face and changes to the button top color. Input areas are recessed into the screen as are list boxes. Not all colors work as well as others. Besides the hideous color schemes you avoid in normal CDD, you need watch how the GUI creates the 3D look with all the colors you choose. While all colors do something not all of them exhibit the "3D look" as well as others. When using the VGAColor product, don't worry, it does not work with GUI. Most of my time has been spent with the VGAColor turned ON within appgen (I recommend it). But, unfortunately the app does not look correct. The following colors do generate both a light and dark shade of the color for optimum 3D effect. Any color that does not, tends to used black. gray, and white. The following are the best of GUI colors. Everything on White (I do not know why they call gray White) Everything on Blue (Still the best VGA Color) Everything on Red (A little red goes a long way) Everything on Cyan (this is a good lokking color) Everything on Brown (Border line looking) Everything on Magenta (not as bad as you might think) Everything on Green (Not the greatest looking) Normally I am in the "I hate Cyan" camp, but under GUI you may want to give it another chance. The rest of the colors are sort of OK. For eamxple Bright is not a good color since there is no color lighter than bright so you loose some of the effect. Many of the others use white as the light component. Black uses only charcoal. Some of the other colors look hideous under GUI, you be the judge on those. My personal favorites are: Blue on White screens with Bright on Blue titles. Warning screens are Red on White. Charcoal on Cyan List boxes Bright on Blue buttons. Yellow on White input text. Blue on White prompts. For down arrow buttons I like Charcoal on white. Special Features ================ GUI does not permit all the screen functions that can be done with normal text mode. There is only one feature I've found that GUI provides that can NOT be done in text mode. This feature is identical to Microsoft Windows. The ability to MOVE the window location is supported by dragging the window title with the mouse. The window will blank and be surrounded with a white outline. The outline will move as you drag the mouse. When you let go of the mouse button, the window will reappear in the new location. Sorry, you can not resize the window. SPEED ===== The GUI is not as fast as text mode (under 3004 only). In fact it may be considered dog slow. The Docs talk about forcing VGA mode for fast display if you use an SVGA adapter. I found the suggested change to SETGRAPHIC(89) did NOT work for me. I did find that by adding: SET VGAGRAPH=VGA to my autoexec.bat worked much much better. For my 486 system it went from much too slow to very nice. You can also set it up in a program .ini file by adding: CLAGRAPH=VGA to the program .ini file. Clarion has promissed even better speed under 3005. Under NO circumstances could I make GUI run fast when launched from the PROJECT - RUN CDD environment option. (see 3005 notes below) Devloping for BOTH GUI & Text Mode ================================== In contrast to the above you can force a GUI app to run in normal text mode by using a set command as: SET VGAGRAPH=ALLTEXT OR an .ini line CLAGRAPH=ALLTEXT This will revert the GUI back to text mode. Any 30 by 80 screens will become virtual and all the text mode effects will come back. It is therefore possible for you to write an app that works for both. I have a hard time with virtual screens, especially when it is only 5 extra rows. The option is real nice if you can design for both worlds at the same time. If you like 25 lines in GUI you can have your apps run in both modes by: 1. Limit all you screens to 80 columns by 25 lines MAXIMUM. 2. Create a .ini for your program and set CLAGRAPH=EGA The above does mean you may not use VGA stuff in the app, since the EGA setting will force the GUI to fill the screen with only 25 lines. If you need VGA or SVGA stuff in your app then you will have to live with partial screens at 25 lines. The above will make the app run under GUI. If you change the CLAGRAPH value to ALLTEXT the app will run under text mode. It will be a little tricky to make all the colors come out right for both systems. Do not worry about the shadows, since GUI will ignore them. Mike Dufort @ Clarion says that shadows will leave holes. I have not seen them, but Mike has always been accurate with things I've read. BUGS version 3004 ================= The following are the known bugs I've found and so it may not be even close to complete. VGAColor is unsupported, though has NO effect, (a bug OR not a feature, you be the judge) not in 3005 either Virtual Screens (beyond 30 lines X 80 Columns) not supported (a bug OR not a feature, you be the judge) not in 3005 either Memo fields do not appear disabled when they are. You ocassionally will get left over pieces of other screens to remain. Sometimes they go away and sometimes not. Not noticed in 3005 There is one situation that will cause a hang. If you use ansi.sys and set your VGA screen to 50 lines and 80 columns from the DOS level and run a GUI app you will hang. Do not call up a GUI app from dos in 50 line mode. This is supposed to be fixed under 3005. Button sizing when using more than one line maybe a bug, maybe a feature. Version 3005 Notes ================== GUI takes a separate patch under 3005, so be sure to get it before using GUI under 3005! Clarion promissed faster GUI under 3005. They delivered big time! GUI is real fast now so any gripes you had should be solved. While not exactly as fast as text mode I find the new speed enhancements to be fantastic. A neater way to set up GUI in appgen is now available in addition to the old way (see your docs) The new way permits you to declare the module name as follows: %clapfx%GUI.OBJ The %clapfx% is replaced during generate with the proper name based on the memory modle you choose in the project file. This is a real benefit! Second you no longer have to define LOADGUI through the worksheet. All you do is add the GUI.INC file on the same screen as the module name. You still have to perform a LOADGUI comand as a program setup though. The GUI.INC include file also gives you access to several new commands related to GUI. BORDERON and BORDEROFF will turn the borders On and Off. New Line, rectangle, and circle commands permit simple line and fill graphics. Now, you'll need to add bar graphs to all your apps! Sorry, you still have to hand code the proc for doing that (maybe not for long). Some other misc commands are available too, but refer to the updated docs for the complete scoop. A minor 3D display problem was fixed on pull down menus, BUT a minor bug was added too. The pull downs now have the right most column dispalyed in the border color. I'm sure Clarion will fix this all too soon. Horizontal scroll bars DON'T. Good news is they don't work in text mode either. I'm certain this is a minor problem to be fixed real soon. COMING ATTRACTIONS ================== I've been working on a new procedure for use with GUI for a POPUP Calendar & Date Lookup Procedure. I've got it finished and so as soon as I can get the docs all fixed up I'll be releasing this for the unheard of price of FREE. Watch for it by the end of October. It will include source and an include file so you can easily integrate it into an app or modify it or hang it up and throw darts at it. I call it my special way of thanking all the folks that have given me tips and saved my behind through all the CDD turmoil we went through to get where we are today (as if we really know where we are).