home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / cell06d.zip / doc / cell.eng next >
Text File  |  1999-02-07  |  10KB  |  291 lines
  1.  
  2.                             Cell Toolkit.
  3.                                 v.06d
  4.  
  5.                        Copyright (C) 1998, 1999
  6.                          Sergey I. Yevtushenko
  7.  
  8. Content.
  9.     1. Overview
  10.     2. Design concepts
  11.     3. Using toolkit
  12.     4. License
  13.  
  14.  
  15.  
  16. 1. Overview.
  17.  
  18.     Cell toolkit is a small library for OS/2 PM. It was designed to
  19. simplify implementation of two important parts of user interface (UI):
  20.  
  21.     - Split views
  22.     - Toolbars
  23.  
  24.     What is split view? This is representation of information in one
  25. window splitted vertically or horizontally into two or more parts
  26. with splitbar which can be moved by user.
  27. You can meet this technique in many popular applications, such as
  28. PMMail, Netscape Navigator, ProNews and many more.
  29.  
  30.     Second target - toolbars - is even more often used part of UI.
  31. But most implementations of toolbars is limited in functionality and
  32. flexibility.
  33.  
  34.  
  35. 2. Design concepts
  36.  
  37.     Idea of Cell Toolkit is simple: any window can be split for two
  38. parts. For example:
  39.  
  40. +---------+
  41. |         |
  42. +---------+
  43. |         |
  44. +---------+
  45.  
  46. or so:
  47.  
  48. +----+----+
  49. |    |    |
  50. |    |    |
  51. |    |    |
  52. +----+----+
  53.  
  54.     Lets allow split parts of window too. Then we can get, for example,
  55. following view:
  56.  
  57. +----+----+
  58. |    |    |
  59. +----+----+
  60. |         |
  61. +---------+
  62.  
  63.     This looks like news client in Netscape Navigator. And below is default
  64. view of PMMail 2.0:
  65.  
  66. +---+-----+
  67. |   |     |
  68. |   +-----+
  69. |   |     |
  70. +---+-----+
  71.  
  72.  
  73.     Lets examine above view.
  74.  
  75.         +---------+
  76.         |         |  Main window
  77.         |         |
  78.         |         |
  79.         +---------+
  80.             / \
  81.            /   \         +-----+  top pane
  82.       +---+     +---+  / |     |
  83.       |   |     |   | /  +-----+
  84.       |   |     |   | \  +-----+  bottom pane
  85.       |   |     |   |  \ |     |
  86.       +---+     +---+    +-----+
  87.       left      right
  88.       pane      pane
  89.  
  90.     Actually at this image does not mentioned important part of split view:
  91. splitbar. Splitbar allows user to resize panels and make it more comfortable
  92. for using.
  93.     But existence of splitbar is not necessary. You can meet less obvious
  94. example of split views: status line. It can be resized, but it also
  95. can be implemented using this approach.
  96.     In general, this approach allows us to cover almost any imaginable
  97. combination of views.
  98.  
  99. 3. Using toolkit
  100.  
  101.     To simplify using of toolkit, API was designed using followin approach:
  102. you create some structures filled with constants, call one function and get
  103. a window created for you. Take a look at example code (simple.c):
  104.  
  105.   CellDef cdLeftPane =
  106.   {
  107.       CELL_WINDOW,
  108.       WC_LISTBOX,
  109.       "List",
  110.       LS_NOADJUSTPOS | WS_VISIBLE,
  111.       ID_LPANE
  112.   };
  113.  
  114. This declaration defines one panel for a split view which will consist of
  115. just a simple listbox. This listbox will have window ID ID_LPANE. Another
  116. declaration:
  117.  
  118.   CellDef cdRightPane =
  119.   {
  120.       CELL_WINDOW,
  121.       WC_MLE,
  122.       "SampleText",
  123.       MLS_BORDER | WS_VISIBLE,
  124.       ID_RPANE
  125.   };
  126.  
  127. This is also a simple MLE with window ID set to ID_RPANE, with border
  128. (MLS_BORDER is set) and with text "Sample Text" in it. The third
  129. declaration is more complicated:
  130.  
  131.   CellDef mainClient =
  132.   {
  133.       CELL_VSPLIT | CELL_SPLITBAR | CELL_SPLIT30x70,
  134.       0,
  135.       "Simple",
  136.       FCF_TITLEBAR | FCF_SYSMENU  | FCF_MENU |
  137.       FCF_MINMAX   | FCF_TASKLIST | FCF_SIZEBORDER |
  138.       0,
  139.       MAIN_FRAME,
  140.       &cdLeftPane,
  141.       &cdRightPane,
  142.       0,
  143.       MainClientProc
  144.   };
  145.  
  146. This declaration will define the main application window. You can note the
  147. difference in flags. Instead of CELL_WINDOW, we create a vertically split
  148. window (CELL_VSPLIT), which will have a splitbar (CELL_SPLITBAR),
  149. initially divided into 30/70% of the window width for left and right parts
  150. of the window, respectively. Window class (second argument) have no
  151. meaning for this case, it is always WC_FRAME. Also, instead of window
  152. creation flags (fourth argument), there are frame creation flags. More
  153. detailed explanations of meanings of these flags can be found in the
  154. OS/2 PM reference book. This window will have ID MAIN_FRAME, two panels
  155. (description for which is in cdLeftPane and cdRightPane respectively), and
  156. have client window procedure "MainClientProc". Passing this parameter
  157. instructs Cell toolkit to subclass main window client and replace
  158. its window procedure with our one. But functionality of its window
  159. procedure is important for Cell Toolkit. So, you need to call the subclassed
  160. procedure at the end of message processing.
  161.     For this purpose you receive a pointer to structure WindowCellCtlData
  162. (defined in cell.h) by issuing a call to WinQueryWindowULong. For now this
  163. structure contains only one field, but you can add any necessary fields.
  164. Because this structure will be allocated for you in the package code and
  165. they need to know the size of it, you should recompile cell.c each time
  166. you make changes in WindowCellCtlData. The rest of the fields will be
  167. filled with 0 with the Cell Toolkit code at cell init time.
  168.  
  169.     Now we ready to create the main window for the application. This is
  170. done by calling CreateCell. This function takes three parameters:
  171. definition of the window (explained above), a window handle for the parent
  172. window and a window handle for the owner window. The last parameter for
  173. the main window should be 0. In all other cases, this parameter should be
  174. set to windows which will receive notification messages from other
  175. windows. Usually this is the main window of the application. You should
  176. note that the main application window definition does not have the flag
  177. WS_VISIBLE set. This is important, because after creating windows, we may
  178. need to do some other work before the application window will appear on
  179. the screen.
  180.  
  181.     What else do we need to do? We need fill controls with some data, add
  182. the toolbar and set the main window position on the screen.
  183.  
  184.     Creating the toolbar is similar to creating windows: you fill
  185. structures, call a function and get a toolbar in your application. The
  186. structure contains three elements:
  187.     - flags,
  188.     - toolbar ID,
  189.     - a pointer to an array of button ID's.
  190.  
  191.     Note that the last element in this array is 0. This
  192. marks the end of the toolbar button definitions. For all IDs listed in
  193. the button array, you should define bitmaps in the resource file and
  194. optionally an element in the stringtable. The element in the string table
  195. is needed only if in the toolbar flags you set the flag TB_BUBBLE. If you
  196. want to divide buttons into groups with gaps between them, you can use the
  197. predefined resource ID TB_SEPARATOR. For this ID you do not need to define
  198. bitmaps or stringtable elements (indeed, separators are not even buttons).
  199.  
  200.     The function CreateToolbar receives two parameters: a pointer to the
  201. toolbar definition structure and the handle of the parent window. Really,
  202. this is just a window with which the toolbar will communicate when
  203. attaching/detaching, and which will own (and receive messages from) the
  204. buttons contained in the toolbar. A few words about toolbar flags: they
  205. define the look of the toolbar only at the start of the application and
  206. can be changed by user. The flags TB_ATTACHED_* define the side of the
  207. parent window to which the toolbar will be attached initially:
  208.  
  209.   TB_ATTACHED_LT - left
  210.   TB_ATTACHED_TP - top
  211.   TB_ATTACHED_RT - right
  212.   TB_ATTACHED_BT - bottom
  213.  
  214. If none of these are specified, the toolbar will float detached from the
  215. parent window. Setting the flag TB_VERTICAL together with one of the TB
  216. flags will be ignored. The user can at any time change the toolbar view.
  217.  
  218.     - Toolbar have a "hand" for dragging, so the user can drag the attached
  219.       toolbar and detach it from the main window.
  220.  
  221.     - By double-clicking with the left mouse button on this "hand" button,
  222.       the user can change the orientation of the detached toolbar
  223.       (horizontal/vertical).
  224.     - By double-clicking with the right mouse button on the "hand" user will
  225.       disable/enable bubble help, if it was enabled.
  226.  
  227.  
  228. Short overview of functions available in Cell Toolkit.
  229.  
  230.     - void ToolkitInit (HAB hab)
  231.       This function should be called before using Cell toolkit.
  232.       It registers some window classes used by toolkit.
  233.  
  234.     - HWND CreateCell (CellDef* pCell, HWND hWndParent, HWND hWndOwner)
  235.       This functions creates cell for given definitions
  236.  
  237.     - HWND CellWindowFromID(HWND hwndCell, ULONG ulID)
  238.       This function tries to wind subwindow with given ID.
  239.       Note that you should have unique window ID's to have it work
  240.       properly.
  241.  
  242.     - HWND CellParentWindowFromID(HWND hwndCell, ULONG ulID)
  243.       Returned window handle is a HWND of frame which contains
  244.       control with given ID.
  245.  
  246.     - void CreateToolbar(HWND hwndCell, TbDef* pTb)
  247.       Creates toolbar and attaches it to given cell window.
  248.       Note: this function assumes that given HWND is window
  249.       handle of Cell window created by call to CreateCell.
  250.       Passing other HWND may produce unpredictable results.
  251.  
  252.     Some additional functions
  253.  
  254.     - LONG GetSplit(HWND, LONG lID)
  255.     - LONG SetSplit(HWND, LONG lID, LONG lProp)
  256.     - void SetSplitType(HWND, LONG lID, LONG lType);
  257.     - LONG GetSplitType(HWND, LONG lID);
  258.  
  259.     Functions above is used for saving/restoring split type
  260.     (horizontal/vertical) and proportions between parts of view.
  261.     Split type is the same as in cell definition. Proportions
  262.     should be given in range 0-100 (actually it will be limited
  263.     by bounds set with CELL_TOP_LIMIT, CELL_BOTTOM_LIMIT).
  264.  
  265.     - void ShowCell(HWND hwnd, LONG lID, BOOL bAction)
  266.     This function allow to show/hide individual cells.
  267.  
  268. 4. License
  269.  
  270.     Well, this can be called a license, but this is just standard
  271.     disclaimer followed by one note.
  272.  
  273.     Disclaimer:
  274.     SOFTWARE IS PROVIDED ATS 'AS IS' BASIS AND YOU CAN USE IT AT YOUR OWN RISK.
  275.  
  276.     Note:
  277.     There is no limits on using library for commercial and/or non-commercial
  278.     purposes.
  279.  
  280.  
  281.  
  282. Comments and suggestions are welcome. You can reach me at:
  283.  
  284. e-mail: evsi@naverex.kiev.ua
  285. FIDO  : 2:463/114.69
  286.  
  287.  
  288. Regards,
  289.     Sergey I. Yevtushenko.
  290.  
  291.