home *** CD-ROM | disk | FTP | other *** search
/ Windoware / WINDOWARE_1_6.iso / demos / tgtp60 / tutor.com / TWQUICK.TXT < prev   
Text File  |  1991-08-16  |  13KB  |  426 lines
  1. TEGL WINDOWS
  2.  
  3. The high-level windows in the TEGL WINDOWS TOOLKIT provide a consistent
  4. graphical interface for your application. Many routines are provided
  5. that are associated with a window or are window relative. A number of
  6. devices are provided that would require a fair bit of coding using the
  7. lower levels of the toolkit.
  8.  
  9.        * Header
  10.        * Local menus
  11.        * Minimize & Maximise buttons
  12.        * Resizers
  13.        * Sliders
  14.        * Dialog management
  15.        * World Coordinates
  16.  
  17. A drawback to the high-level windows is the necessity of coding a
  18. redraw event for windows that are resizeable.
  19.  
  20. Here is a simple window:
  21.  
  22. BEGINFILE> twwin1.pas
  23. {-- twwin1.pas}
  24. USES teglmain, twcommon, twkernel;
  25.  
  26. VAR wf : WinFramePtr;
  27.  
  28. BEGIN
  29.   twEasyStart;
  30.  
  31.   twInit(wf,100,50,300,150);
  32.   twSetHeader(wf,'A Simple Window');
  33.   twDrawWindowFrame(wf);
  34.  
  35.   TeglSupervisor;
  36. END.
  37.  
  38. ENDFILE>
  39.  
  40. When you compile and run this program you'll get a window with a header
  41. and resize areas.
  42.  
  43. Lets examine what each step in this programs does.
  44.  
  45. The first call to twEasyStart does the graphics system and window
  46. manager initialization including autodetection of the graphics
  47. hardware and clearing the screen. Additionally it places an exit
  48. button in the lower right corner of the screen so you can always exit
  49. your program.
  50.  
  51. twInit creates a window frame (the first parameter wf is a VAR
  52. WinFramePtr) memory block, the numbers indicate the screen area
  53. that the window should occupy (x1, y1, x2, y2). twInit must always
  54. be called before an other routines that have a WinFramePtr as their
  55. first argument.
  56.  
  57. twSetHeader says this window will have a header displayed (default
  58. is no header) and what is displayed in it.
  59.  
  60. twDrawWindowFrame actually draws the window on the screen. This is
  61. always called after all the conditions for a window have been set.
  62.  
  63. TeglSupervisor is the event-supervisor. It will poll for events
  64. (key-presses and mouse clicks) and call up the appropriate event-handler
  65. as required.
  66.  
  67. The high-level windows have a number of pre-defined event-handlers
  68. that are automatically installed. There is the resizing events which
  69. look after the borders of the window so that a mouse click can stretch
  70. or shrink the window. Also there is the minimize and maximize buttons.
  71. The minimize button will shrink a window to an icon while the maximize
  72. button expands it to fill the entire screen.
  73.  
  74. CONTROL FUNCTIONS
  75.  
  76. FindWinFrame(frame : ImageStkPtr): WinFramePtr;
  77.  
  78. This function is used to locate a WinFramePtr that is associated with
  79. a frame (ImageStkPtr). It is called on entry to an event-handler to
  80. determine what window invoked it.
  81.  
  82. twSelect(wf: WinFramePtr);
  83.  
  84. This function will select the window. This should be called on entry
  85. to any event-handler that uses a window, it does internal checks and
  86. sets the viewport to the working area.
  87.  
  88. GLOBAL WINDOW SETUP
  89.  
  90. twSetGlobalButtonSize(width, height: byte);
  91.  
  92. Set the size of the buttons on the window. Generally if the defaults
  93. are not satisfactory then this can be changed but should be done at
  94. start up before any windows are drawn. This affects all windows.
  95.  
  96. twSetGlobalSliderSize(UpDown, LeftRight: Byte);
  97.  
  98. Sets the size of the slider thumb (the button that slides). This only
  99. affects on dimension of the slider thumbs, the other is set to conform
  100. to the button sizes.
  101.  
  102. twSetGlobResizeArea(Width, Height: Byte);
  103.  
  104. Sets the size of the resize corner areas of the window border.
  105. Width is the x distance (in pixels) and Height is the y distance.
  106. The thickness of the border is used to complete the resize areas, this
  107. defaults to 4 pixels and can be changed on individual windows.
  108.  
  109. twSetHeaderFont(Font : Pointer);
  110.  
  111. Sets the font that all subsequent windows will use for headers and
  112. menus.
  113.  
  114. This example sets these global items to illustrate how the window
  115. style is affected. The best use of these items is to control the
  116. window look on different video displays and would best be set at
  117. the start of a program and left alone during the run.
  118.  
  119. BEGINFILE> twwin2.pas
  120. {-- twwin2.pas}
  121.  
  122. USES teglfont,moreicon,tgraph,
  123.      teglunit,teglmain,
  124.      twcommon, twkernel;
  125.  
  126. {$F+}
  127. VAR wf : WinFramePtr;
  128.  
  129.  
  130.  
  131. BEGIN
  132.   twEasyStart;
  133.  
  134.   twSetGlobalButtonSize(24,12);
  135.   twSetGlobalSliderSize(36,8);
  136.   twSetGlobalResizeArea(50,20);
  137.   twSetHeaderFont(@f8x12bol);
  138.   twInit(wf,100,50,300,170);
  139.     twSetHeader(wf,'Common Window characteristics');
  140.     twSetWindowStyle(wf,stdbox);
  141.     twSetUpDownSlider(wf,TRUE);
  142.     twSetLeftRightSlider(wf,TRUE);
  143.   twDrawWindowFrame(wf);
  144.  
  145.   TeglSupervisor;
  146. END.
  147.  
  148. ENDFILE>
  149.  
  150. WINDOW FEATURES
  151.  
  152. The following functions set features on a window that affect only that
  153. window. Note that each one requires a WinFramePtr at the first
  154. argument.
  155.  
  156. twSetBorderColor(wf: WinFramePtr; color: Byte);
  157.  
  158. Sets the color of the window border. The border is the one pixel outline.
  159.  
  160. twSetCloseEvent(wf: WinFramePtr; CloseEvent: CallProc);
  161.  
  162. Sets the event to call when a window is disposed of. The CloseEvent does
  163. not have to be set (a default one is in place).
  164.  
  165. twSetDisplayFont(wf: WinFramePtr; font: pointer);
  166.  
  167. Sets the font to use with the window. This affects the header and menus.
  168.  
  169. twSetMaximize(wf: WinFramePtr; tf: Boolean);
  170.  
  171. Sets whether a window is minimize/maximizeable. If TRUE then the
  172. window will have the minimize/maximize buttons. Only has an effect on
  173. windows with a header.
  174.  
  175. twSetRedraw(wf: WinFramePtr; Redraw: CallProc);
  176.  
  177. Sets the redrawing function for a window. The redrawing function is
  178. an event-handler. This function is called after the kernel draws the
  179. window (border, buttons, menu etc.) when first created and any time the
  180. window must be redraw, like after it has been re-sized.
  181.  
  182. twSetHeader(wf: WinFramePtr; s : String);
  183.  
  184. Sets the window header to s. Window header must be set to enable the
  185. minimize/maximize buttons.
  186.  
  187. twSetThickness(wf: WinFramePtr; Thickness: Byte);
  188.  
  189. Sets the thickness of the window border. Thickness cannot be less than
  190. one. The thickness affects the size of the resize areas (if resizing is
  191. enabled for the window).
  192.  
  193. twSetWinFrameColors(wf: WinFramePtr; Color1, Color2: Byte);
  194.  
  195. Sets the colors to use on the upper left and lower right of the window.
  196.  
  197. twSetWindowStyle(wf: WinFramePtr; Style: FrameDrawFunc);
  198.  
  199. Sets the drawing function to draw the border of the window frame.
  200. Currently there are two drawing functions, stdbox and bevbox.
  201.  
  202. ------------------------------------------------------------------
  203.  
  204. This example uses many of window features, you don't need to set them
  205. all, the defaults are usually fine, but by changing them around you
  206. can see the effects.
  207.  
  208. BEGINFILE> twwin3.pas
  209. {-- twwin3.pas}
  210. USES moreicon,tgraph,
  211.      teglunit,teglmain,
  212.      twcommon, twkernel;
  213.  
  214. {$F+}
  215. VAR wf : WinFramePtr;
  216.  
  217.  
  218.  
  219. {-- RedrawIt is a standard event-handler. It is called after }
  220. {-- the window standard items have been drawn. }
  221.  
  222. Function RedrawIt(ifs: ImageStkPtr; ms: MsClickPtr): Word;
  223.   VAR wf: WinFramePtr;
  224.   BEGIN
  225.     wf := findWinFrame(ifs);
  226.     twPutPict(wf,1,1,@IMAGESYSTEM,BLACK);
  227.   END;
  228.  
  229. {-- this is the close event for the window. }
  230.  
  231. Function CloseIt(ifs: ImageStkPtr; ms: MsClickPtr): Word;
  232.   VAR wf: WinFramePtr;
  233.       i : Integer;
  234.       color : Integer;
  235.   BEGIN
  236.     wf := findWinFrame(ifs);
  237.     prepareforupdate(ifs);
  238.     {-- prove that we are going through here }
  239.     color := 0;
  240.     for i := 0 to 100 do
  241.       BEGIN
  242.         twSetFillcolor(wf,color);
  243.         twClear(wf);
  244.         inc(color);
  245.         if color > 15 then color := 0;
  246.       END;
  247.     commitupdate;
  248.     {-- then call close to actually dispose of the window }
  249.     twClose(wf);
  250.   END;
  251.  
  252.  
  253. BEGIN
  254.   twEasyStart;
  255.  
  256.   twInit(wf,100,50,300,170);
  257.     twSetHeader(wf,'Window characteristics');
  258.     twSetThickness(wf,6);
  259.     twSetFillColor(wf,GREEN);
  260.     twSetBorderColor(wf,BLACK);
  261.     twSetWinFrameColors(wf,cyan,Magenta);
  262.     twSetMaximize(wf,FALSE);    {-- no minimize/maximize}
  263.     twSetWindowStyle(wf,BevBox);
  264.     twSetRedraw(wf,RedrawIt);
  265.     twSetCloseEvent(wf,CloseIt);
  266.   twDrawWindowFrame(wf);
  267.  
  268.   TeglSupervisor;
  269. END.
  270.  
  271. ENDFILE>
  272.  
  273. WINDOW FUNCTIONS
  274.  
  275. twClear(wf: WinFramePtr);
  276.  
  277. Clears the window to the color set by twSetFillColor.
  278.  
  279. twScrollDown(wf: WinFramePtr; Num: Integer);
  280. twScrollUp(wf: WinFramePtr; Num: Integer);
  281.  
  282. These functions will scroll the working area of the window up or down
  283. by Num pixels. The area cleared is filled using the current fillcolor
  284. set by twSetFillColor.
  285.  
  286. Sliders -
  287.  
  288. twSetUpDownSlider(wf: WinFramePtr; Active: Boolean);
  289. twSetLeftRightSlider(wf: WinFramePtr; Active: Boolean);
  290.  
  291. These enable (or disable) the sliders from being attacted to a
  292. window. TRUE turns sliders on, FALSE turns them off. If the slider
  293. is changed after the window is displayed then it must be redrawn for
  294. it to take effect.
  295.  
  296. Sliders won't be displayed if a window becomes too small.
  297.  
  298. twSetLeftRightEvent(wf: WinFramePtr; Event: CallProc);
  299. twSetUpDownEvent(wf: WinFramePtr; Event: CallProc);
  300.  
  301. These set the event to be called after a slider has been moved. This
  302. means either the slider thumb or the end point buttons.
  303.  
  304. twSetLeftRightRange(wf: WinFramePtr; Range, Step: Integer);
  305. twSetUpDownRange(wf: WinFramePtr; Range, Step: Integer);
  306.  
  307. The slider movement can be gauged by setting its range (from 0 to
  308. range) and the step. Range is an arbitrary value that would reflect the
  309. item that the slider is used to scroll. Step is the increment value to
  310. use with the end point buttons.
  311.  
  312. Menus -
  313.  
  314. Two functions provide for a straight forward local menu facility. On both
  315. the string parameter is the displayed menu selection. Active is to set
  316. whether the menu item is to be active (clickable). If a menu item is
  317. passed with tildes '~' around a character then that item is displayed
  318. with an underscore and the appropriate keypress is trapped (if the
  319. window is active).
  320.  
  321. twMenuItem(wf: WinFramePtr; s : String; Active: Boolean);
  322.  
  323. Add a local bar menu item to the window. After adding a bar menu item
  324. the sub menu items must be delared immediately afterward using
  325. twSubMenuItem.
  326.  
  327. twSubMenuItem(wf: WinFramePtr; s: String; Active: Boolean; Event: CallProc);
  328.  
  329. Add a submenu item to the local bar menu item most recently added.
  330. Event is the event-handler to call when the sub menu item is selected.
  331.  
  332.  
  333. An important consideration with windows that have local menus is the
  334. ImageStkPtr that is passed to the event-handler. It is not the ImageStkPtr of
  335. the Window but of the smaller frame that the menu is displayed in. This
  336. is consistent in that an event-handler is always passed the frame that
  337. the mouse click originated on. To determine what window this event-handler
  338. is being called from use the related stack as in ifs^.related stack.
  339.  
  340. BEGINFILE> twwin4.pas
  341. {-- twwin4.pas}
  342. USES moreicon,tgraph,
  343.      teglunit,teglmain,
  344.      twcommon, twkernel;
  345.  
  346. {$F+}
  347. VAR wf : WinFramePtr;
  348.  
  349.  
  350.  
  351. {-- RedrawIt is a standard event-handler. It is called after }
  352. {-- the window standard items have been drawn. }
  353.  
  354. Function RedrawIt(ifs: ImageStkPtr; ms: MsClickPtr): Word;
  355.   VAR wf: WinFramePtr;
  356.   BEGIN
  357.     wf := findWinFrame(ifs);
  358.     twPutPict(wf,10,10,@IMAGESYSTEM,BLACK);
  359.   END;
  360.  
  361. {-- this is the close event for the window. }
  362.  
  363. Function CloseIt(ifs: ImageStkPtr; ms: MsClickPtr): Word;
  364.   VAR wf: WinFramePtr;
  365.       i : Integer;
  366.       color : Integer;
  367.   BEGIN
  368.     wf := findWinFrame(ifs);
  369.     prepareforupdate(ifs);
  370.     {-- prove that we are going through here }
  371.     color := 0;
  372.     for i := 0 to 100 do
  373.       BEGIN
  374.         twSetFillcolor(wf,color);
  375.         twClear(wf);
  376.         inc(color);
  377.         if color > 15 then color := 0;
  378.       END;
  379.     commitupdate;
  380.     {-- then call close to actually dispose of the window }
  381.     twClose(wf);
  382.   END;
  383.  
  384. {-- this event-handler just chains to CloseIt, the important }
  385. {-- notation here is the use of the related stack for local }
  386. {-- menu selections to determine the correct WinFramePtr }
  387.  
  388. Function MenuCloseIt(ifs: ImageStkPtr; ms: MsClickPtr): Word;
  389.   BEGIN
  390.     MenuCloseIt := CloseIt(ifs^.relatedStack,ms);
  391.   END;
  392.  
  393.  
  394. BEGIN
  395.   twEasyStart;
  396.  
  397.   twInit(wf,100,50,300,190);
  398.     twSetHeader(wf,'Window with a local menu');
  399.     twSetMaximize(wf,FALSE);    {-- no minimize/maximize}
  400.     twSetRedraw(wf,RedrawIt);
  401.     twSetCloseEvent(wf,CloseIt);
  402.     twMenuItem(wf,'~F~ile',TRUE);
  403.       {-- NilUnitProc is just a dummy event-handler, use it }
  404.       {-- as a place holder when you are just building an interface }
  405.       twSubMenuItem(wf,'~O~pen',TRUE,NilUnitProc);
  406.       twSubMenuItem(wf,'-',FALSE,NilUnitProc);
  407.       twSubMenuItem(wf,'E~x~it',TRUE,MenuCloseIt);
  408.     twMenuItem(wf,'~D~raw',TRUE);
  409.       twSubMenuItem(wf,'~A~rc',FALSE,NilUnitProc);
  410.       twSubMenuItem(wf,'~C~ircle',FALSE,NilUnitProc);
  411.       twSubMenuItem(wf,'~E~llipse',FALSE,NilUnitProc);
  412.       twSubMenuItem(wf,'~R~ectangle',FALSE,NilUnitProc);
  413.   twDrawWindowFrame(wf);
  414.  
  415.   TeglSupervisor;
  416. END.
  417.  
  418. ENDFILE>
  419.  
  420.  
  421. Any of the example programs that start with a 'TW' are examples of
  422. the high-level window interface.
  423.  
  424. -------------------------------------------------------------------
  425. END TWQUICK.TXT
  426.