home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 7 / 07.iso / c / c082_122 / 7.ddi / RWDOC.ZIP / CUSTCNTL.RW < prev    next >
Encoding:
Text File  |  1992-06-10  |  34.5 KB  |  863 lines
  1.                            CUSTCNTL.RW
  2.                            ===========
  3.  
  4.  
  5. 1        Creating custom control classes
  6. ----------------------------------------
  7.  
  8. Windows provides standard control classes, such as list boxes and
  9. radio buttons, that you can add to your dialog box resources. In
  10. addition to these standard classes, Resource Workshop also lets
  11. you create and use custom control classes. This file describes
  12. the functions you'll need to use to make your custom controls
  13. accessible to Resource Workshop.
  14.  
  15. See Chapter 4 in the Resource Workshop User's guide for
  16. descriptions of the standard menu controls and of how to load and
  17. use a custom control library.
  18.  
  19. You must store your custom controls in a dynamic-link library
  20. (DLL) file. For an example of how to use the custom control
  21. application program interface described in this file and to
  22. create a sample DLL file, see the BITBTN demonstration programs
  23. on your Resource Workshop distribution disks. These programs come
  24. in a Pascal version and a C version.
  25.  
  26. The DLL file must contain functions that enable Resource Workshop
  27. to work with the custom controls just as it works with the
  28. standard Windows controls. In particular, you must implement the
  29. ListClasses function and export it by name. This function
  30. provides information to Resource Workshop about the custom
  31. control classes in the DLL.
  32.  
  33. You must also provide the following functions for each custom
  34. control window class:
  35.  
  36. - Info
  37. - Style
  38. - Flags
  39.  
  40. These functions can have any name. They must, however, be
  41. exported by the DLL, and pointers to them must be supplied in the
  42. ListClasses function.
  43.  
  44. The remainder of this file is divided into two sections, the
  45. first for C programmers and the second for Pascal programmers.
  46. The C programming section follows immediately. To skip to the
  47. Pascal portion, search for "Pascal programming section".
  48.  
  49.  
  50. 2        C programming section
  51. ------------------------------
  52.  
  53. 2.1      ListClasses function
  54. -----------------------------
  55.  
  56. ListClasses is a programmer-implemented function that passes
  57. information about the custom control classes back to Resource
  58. Workshop. Exporting ListClasses marks your DLL as supporting this
  59. custom control specification.
  60.  
  61. If ListClasses is present in the DLL, Resource Workshop calls the
  62. function, passing information about itself along with two utility
  63. function variables used in editing the custom control.
  64.  
  65. ListClasses should return a handle to global memory allocated by
  66. calling GlobalAlloc.  The memory referenced by this handle holds
  67. a structure of type CTLCLASSLIST, which describes the controls in
  68. the library.  CTLCLASSLIST is described later in this section.
  69. The handle is freed by Resource Workshop and should not be freed
  70. by the DLL.
  71.  
  72. Return value:
  73.  
  74.     Returns a global handle to the data structure.
  75.  
  76. Syntax:
  77.  
  78.    HGLOBAL CALLBACK ListClasses( LPSTR szAppClass, UINT wVersion,
  79.    LPFNLOADRES fnLoad, LPFNEDITRES fnEdit);
  80.  
  81. Parameters:
  82.  
  83.     szAppClass     The class name of the main window of the
  84.                    calling application. This class name can be
  85.                    used by the custom control to determine if it
  86.                    is running under a resource editor. If
  87.                    szAppClass is "rwswnd", the calling
  88.                    application is Resource Workshop.
  89.  
  90.     wVersion       The version number of the calling application.
  91.                    The major version is in the high-order byte
  92.                    and the minor version in the low-order byte.
  93.                    For example, version 1.02 is 0x0102.
  94.  
  95.     fnLoad         A pointer to a function a custom control can
  96.                    use to obtain a binary version of any resource
  97.                    in the project being edited by the calling
  98.                    application--the equivalent of the Windows API
  99.                    function LoadResource(). The function takes
  100.                    two parameters, a resource type name and a
  101.                    resource name. The custom control is
  102.                    responsible for freeing the global handle (if
  103.                    any) returned by this function.
  104.  
  105.     fnEdit         A pointer to a function a custom control can
  106.                    use to start a resource editor for any
  107.                    resource in the project being edited by
  108.                    Resource Workshop. It takes two parameters, a
  109.                    resource type name and a resource name.
  110.  
  111. Data structures:
  112.  
  113.     typedef struct
  114.     {
  115.       LPFNINFO  fnRWInfo;             // Info function
  116.       LPFNSTYLE fnRWStyle;            // Style function
  117.       LPFNFLAGS fnFlags;              // Flags function
  118.       char  szClass[ CTLCLASS];       // Class name
  119.  
  120.     } RWCTLCLASS, FAR *LPRWCTLCLASS;
  121.  
  122.     typedef struct {
  123.       short  nClasses;          // Number of classes in list
  124.       RWCTLCLASS Classes[];           // Class list
  125.     } CTLCLASSLIST, FAR *LPCTLCLASSLIST;
  126.  
  127.     The CTLCLASSLIST structure contains a variable number of
  128.     RWCTLCLASS strucures, the number of which is determined by
  129.     the nClasses field.
  130.  
  131.     Each control class in the DLL must have a corresponding
  132.     RWCTLCLASS structure in the CTLCLASSLIST. The szClass field
  133.     contains the name with which the class was registered. For
  134.     example, if you called RegisterClass giving the class name as
  135.     "MYBUTTON", szClass must be "MYBUTTON".
  136.  
  137. The function variables Info, Style, and Flags--which correspond
  138. to the pointers fnRWInfo, fnRWStyle, and fnFlags--are described
  139. in the following sections.
  140.  
  141.  
  142. 2.2      Info function
  143. ----------------------
  144.  
  145. The Info function is called by Resource Workshop to retrieve
  146. information about the control class, including the string to add
  147. to the control menu and the bitmap to add to the tool palette.
  148. The function returns a memory handle that can be allocated by
  149. GlobalAlloc. This handle must refer to memory that contains a
  150. RWCTLINFO structure. Like ListClasses, the handle returned by
  151. Info is freed by Resource Workshop and should not be freed by the
  152. DLL. This function is called once by Resource Workshop upon
  153. loading the DLL.
  154.  
  155. Syntax:
  156.  
  157.     HGLOBAL CALLBACK Info( void);
  158.  
  159. Parameters:
  160.  
  161.     None.
  162.  
  163. Structure:
  164.  
  165.     The RWCTLINFO structure, defined by a typedef in the file
  166.     CUSTCNTL.H, has two basic parts:
  167.  
  168.     - The first part has a fixed length and provides information
  169.       about the whole control class.
  170.  
  171.     - The second part is a variable-length array of fixed-length
  172.       records. Each record provides information about a
  173.       particular type or subclass of the control.
  174.  
  175.     /* general size definitions */
  176.     #define     CTLTYPES   12   /* number of control types   */
  177.     #define     CTLDESCR   22   /* size of control menu name */
  178.     #define     CTLCLASS   20   /* max size of class name    */
  179.     #define     CTLTITLE   94   /* max size of control text  */
  180.  
  181.      typedef struct {
  182.        UINT         wVersion;            /* control version */
  183.        UINT         wCtlTypes;           /* control types */
  184.        char         szClass[CTLCLASS];   /* control class name */
  185.        char         szTitle[CTLTITLE];   /* control title */
  186.        char         szReserved[10];    // reserved for future use
  187.        RWCTLTYPE    Type[CTLTYPES];      /* control type list */
  188.      } RWCTLINFO;
  189.  
  190.      typedef RWCTLINFO *RWPCTLINFO;
  191.      typedef RWCTLINFO FAR *LPRWCTLINFO;
  192.  
  193.     wVersion       The version number of the custom control
  194.                    library. The major version is in the
  195.                    high-order byte and the minor version is in
  196.                    the low-order byte. For example, version 1.02
  197.                    is 0x0102. This field is not used by Resource
  198.                    Workshop.
  199.  
  200.     wCtlTypes      The number of control sub-types defined in the
  201.                    Type array.
  202.  
  203.     szClass        The name of the class as registered with
  204.                    Windows.  This is duplicated from the
  205.                    CTLCLASSLIST structure to retain upward
  206.                    compatiblity with the Windows custom control
  207.                    specificiation.
  208.  
  209.     szReserved     Space reserved for future expansion.  Must be
  210.                    cleared to null characters (0).
  211.  
  212.     Type           An array of sub-type description structures of
  213.                    type RWCTLTYPE.
  214.  
  215.     /*
  216.      * RWCTLTYPE DATA STRUCTURE
  217.      *
  218.      * This data structure is returned by the control options
  219.      * function while inquiring about the capabilities of a
  220.      * particular control. Each control may contain various types
  221.      * (with predefined style bits) under one general class.
  222.      *
  223.      * The width and height fields provide the application with
  224.      * a suggested size. Use pixels or dialog units for the
  225.      * values in these fields. If you use pixels, turn on the
  226.      * most significant bit (MSB). If you use dialog units, turn
  227.      * off the MSB.
  228.      *
  229.      */
  230.  
  231.      typedef struct {
  232.        UINT         wType;               /* type style */
  233.        UINT         wWidth;              /* suggested width */
  234.        UINT         wHeight;             /* suggested height */
  235.        DWORD        dwStyle;             /* default style */
  236.        char         szDescr[CTLDESCR];   /* menu name */
  237.        HBITMAP      hToolBit;            // Toolbox bitmap
  238.        HCURSOR      hDropCurs;           // Drag and drop cursor
  239.      } RWCTLTYPE, FAR * LPRWCTLTYPE;
  240.  
  241.     wType          A user-defined value used to indicate the
  242.                    sub-type of the control.  This value is not
  243.                    used by Resource Workshop.
  244.  
  245.     wWidth         The default width for the control.  Resource
  246.                    Workshop will use this value if, for example,
  247.                    the control is created by dragging the icon
  248.                    from the tool palette.  wWidth is in dialog
  249.                    coordinates unless the most significant bit is
  250.                    set, in which case the value is in pixels. For
  251.                    example, a value of "32" is 32 in dialog
  252.                    coordinates, but the value "32 | 0x8000" is in
  253.                    pixels.
  254.  
  255.     wHeight        The default height for the control.  Resource
  256.                    Workshop will use this value if, for example,
  257.                    the control is created by dragging the icon
  258.                    from the tool palette.  wHeight is in dialog
  259.                    coordinates unless the most significant bit is
  260.                    set, in which case the value is in pixels. For
  261.                    example, a value of "32" is 32 in dialog
  262.                    coordinates, but the value "32 | 0x8000" is in
  263.                    pixels.
  264.  
  265.     wStyle         The default style Resource Workshop will use
  266.                    to create the Window.  This is the key field
  267.                    that you will use to distinguish one subtype
  268.                    from another.
  269.  
  270.     szDescr        The description of the control subtype.  This
  271.                    text is used by Resource Workshop to construct
  272.                    a menu item that the user can use to create an
  273.                    instance of your custom control.
  274.  
  275.     hToolBit       A handle to a bitmap which will be placed on
  276.                    the tool palette.  Resource Workshop requires
  277.                    the bitmap be a 22x22 black and gray bitmap
  278.                    containing a 2-pixel border that is white on
  279.                    the top and left and black on the bottom and
  280.                    right. You can use the bitmaps contained in
  281.                    BITBTN.RES as templates.
  282.  
  283.     hDropCurs      A cursor to be used while dragging the control
  284.                    from the tool palette.
  285.  
  286.  
  287. 2.3      Style function
  288. -----------------------
  289.  
  290. The Style function makes it possible for you to edit your custom
  291. control. You must first create an appropriate dialog box in
  292. Resource Workshop and then implement a Boolean function that
  293. displays that dialog box. Resource Workshop calls this function
  294. whenever you initiate a request to edit the custom control.
  295. Resource Workshop passes the function a handle to the window that
  296. is the parent of the dialog, a handle to memory containing the
  297. RWCTLSTYLE structure, and two function variables for string
  298. conversion.
  299.  
  300. Return value:
  301.  
  302.     If the user changes any options for the control, this
  303.     function's return value is TRUE. If the user doesn't make any
  304.     changes or if an error prevents changes, the return value is
  305.     FALSE.
  306.  
  307. Syntax:
  308.  
  309.     BOOL CALLBACK Style( HWND hWnd, HGLOBAL hCtlStyle,
  310.     LPFNSTRTOID lpfnStrToId, LPFNIDTOSTR lpfnIdToStr);
  311.  
  312. Parameters:
  313.  
  314.     hWnd           A handle to the parent window of the dialog
  315.                    box displayed by this function.
  316.  
  317.     hCtlStyle      A handle to global memory containing the
  318.                    RWCTLSTYLE structure to be edited.
  319.  
  320.     lpfnStrToId    A function variable that converts a string
  321.                    into a control ID for the wId field of
  322.                    RWCTLSTYLE. This allows the user to enter the
  323.                    control ID using a constant identifier. This
  324.                    routine evaluates the string as an expression,
  325.                    returning the result.  The ID can be converted
  326.                    back into a string by calling lpfnIdToStr.
  327.  
  328.     lpfnIdToStr    A function variable that converts the control
  329.                    ID in the wId field of RWCTLSTYLE to a string
  330.                    for editing. The ID can be converted back into
  331.                    a word by calling lpfnStrToId. This function
  332.                    variable allows the user to see the symbolic
  333.                    constant that represents the control ID
  334.                    instead of the word value.
  335.  
  336. Data structure:
  337.  
  338.     /*
  339.      * CONTROL-STYLE DATA STRUCTURE
  340.      *
  341.      * The class style function uses this data structure
  342.      * to set or reset various control attributes.
  343.      *
  344.      */
  345.  
  346.     typedef struct {
  347.       UINT         wX;                  /* x origin of control */
  348.       UINT         wY;                  /* y origin of control */
  349.       UINT         wCx;                 /* width of control */
  350.       UINT         wCy;                 /* height of control */
  351.       UINT         wId;                 /* control child id */
  352.       DWORD        dwStyle;             /* control style */
  353.       char         szClass[CTLCLASS];   // name of control class
  354.       char         szTitle[CTLTITLE];   /* control text */
  355.       BYTE         CtlDataSize;         /* control data size */
  356.       BYTE         CtlData[ CTLDATALENGTH]; /* control data */
  357.     } RWCTLSTYLE;
  358.  
  359.     typedef RWCTLSTYLE *   PRWCTLSTYLE;
  360.     typedef RWCTLSTYLE FAR *   LPRWCTLSTYLE;
  361.  
  362.     wX             The horizontal (X) location of the control in
  363.                    dialog coordinates.
  364.  
  365.     wY             The vertical (Y) location of the control in
  366.                    dialog coordinates.
  367.  
  368.     wCx            The width of the control in dialog
  369.                    coordinates.
  370.  
  371.     wCy            The height of the control in dialog
  372.                    coordinates.
  373.  
  374.     wId            The control's ID value.  This value must be
  375.                    converted to a string by calling lpfnIdToStr
  376.                    before being displayed for editing. It must be
  377.                    converted back into a word for storage by
  378.                    calling lpfnStrToId after editing.
  379.  
  380.     dwStyle        The style flags of the control.
  381.  
  382.     szClass        The class name of the control.
  383.  
  384.     szTitle        The title of the control.
  385.  
  386.     CtlDataSize    Windows allows controls in a resource file to
  387.                    have up to 255 bytes of control-defined data.
  388.                    This field indicates how much of that space is
  389.                    being used by the control.  The data is stored
  390.                    in CtlData.
  391.  
  392.     CtlData        This field holds up to 255 bytes of
  393.                    control-specific data.  The amount used must
  394.                    be recorded in the CtlDataSize field.  The use
  395.                    of this data area is user-defined.
  396.  
  397. When you save your project, Resource Workshop saves the CtlData
  398. array into the .RC or .RES file.
  399.  
  400. To enable a custom control to access this array from within your
  401. program at run time, lParam of the WM_CREATE message points to a
  402. CREATESTRUCT data structure. The CREATESTRUCT structure contains
  403. a field, lpCreateParams, that is a pointer to the extra data you
  404. stored in the CtlData array. If the pointer is NULL, there is no
  405. CtlData.
  406.  
  407. The CtlDataSize variable is not available to your program. To
  408. make the size data accessible to your program, the CtlData array
  409. should either contain a fixed amount of data, or its first byte
  410. should contain the length of the data.
  411.  
  412. The Style function first converts the ID to a string by passing
  413. the numerical ID value to LPFNIDTOSTR. The Style function then
  414. displays the string in the dialog box.
  415.  
  416. If the user changes the string that's returned by LPFNIDTOSTR,
  417. the Style function verifies the string by passing it to
  418. LPFNSTRTOID, which determines if the string is a valid constant
  419. expression. If LPFNSTRTOID returns a zero in the LOWORD, the ID
  420. is illegal and is displayed in the dialog box so the user can
  421. change it to a valid ID. If LPFNSTRTOID is successful, it returns
  422. a nonzero value in the LOWORD and the ID in the HIWORD.
  423.  
  424.  
  425. 2.4      Flags function
  426. -----------------------
  427.  
  428. The Flags function is used by Resource Workshop to translate the
  429. style of a control into text.  Resource Workshop inserts the text
  430. into the .RC file being edited.  The function must only convert
  431. the values unique to the control.  For example, if you were
  432. creating a Flags function for the Windows button class, you would
  433. only examine the lower sixteen bits of Flags and translate them
  434. into one of the bs_XXXX constants.
  435.  
  436. Return value:
  437.  
  438.     Returns the number of bytes copied into the destination
  439.     string. Returns 0 if the Flags word is not valid or the
  440.     string exceeds MaxString in length.
  441.  
  442. Syntax:
  443.  
  444.     UINT CALLBACK Flags(DWORD dwFlags, LPSTR lpStyle, UINT
  445.     wMaxString);
  446.  
  447. Parameters:
  448.  
  449.     dwFlags        The style of the control to be translated into
  450.                    text.  This field is derived from the dwStyle
  451.                    field of the RWCTLSTYLE structure passed to
  452.                    the Style function variable.
  453.  
  454.     lpStyle        The location to write the translated
  455.                    text.
  456.  
  457.     wMaxString     The maximum number of bytes the Flags function
  458.                    can write into Style.
  459.  
  460.  
  461. 3        Pascal programming section
  462. -----------------------------------
  463.  
  464. 3.1      ListClasses function
  465. -----------------------------
  466.  
  467. ListClasses is a programmer-implemented function that passes
  468. information about the custom control classes back to Resource
  469. Workshop. Exporting ListClasses marks your DLL as supporting this
  470. custom control specification.
  471.  
  472. If ListClasses is present in the DLL, Resource Workshop calls the
  473. function, passing information about itself along with two utility
  474. function variables used in editing the custom control.
  475.  
  476. ListClasses should return a handle to global memory allocated by
  477. calling GlobalAlloc.  The memory referenced by this handle holds
  478. a record of type TCtlClassList, which describes the controls in
  479. the library.  TCtlClassList is described later in this section.
  480. The handle is freed by Resource Workshop and should not be freed
  481. by the DLL.
  482.  
  483. Syntax:
  484.  
  485.     function ListClasses(AppName: PChar; Version: Word;
  486.       Load: TLoad; Edit: TEdit): THandle; export;
  487.  
  488. Return value:
  489.  
  490.     Returns a handle to global memory containing a record of type
  491.     TCtlClassList.
  492.  
  493. Parameters:
  494.  
  495.     AppName        The class name of the main window of the
  496.                    calling application.  This value can be used
  497.                    by the custom control to determine if it is
  498.                    running under a resource editor. If AppName is
  499.                    'rwswnd', the calling application is Resource
  500.                    Workshop.
  501.  
  502.     Version        The version number of the calling application.
  503.                    The major version is in the high-order byte
  504.                    and the minor version in the low-order byte.
  505.                    For example, version 1.02 is $0102.
  506.  
  507.     Load           A function variable that custom controls can
  508.                    use to obtain the handle of a resource in the
  509.                    project being edited by the calling
  510.                    application (the equivalent of the Windows API
  511.                    function LoadResource). The function takes two
  512.                    parameters, a resource type name and a
  513.                    resource name. The custom control is
  514.                    responsible for freeing the global handle (if
  515.                    any) returned by this function.
  516.  
  517.     Edit           A function variable that custom controls can
  518.                    use to start a resource editor for any
  519.                    resource in the project being edited by
  520.                    Resource Workshop. The function takes two
  521.                    parameters, a resource type name and a
  522.                    resource name.
  523.  
  524. Return value records:
  525.  
  526.     PCtlClassList = ^TCtlClassList;
  527.     TCtlClassList = record
  528.       nClasses: Integer;           { Number of classes in list }
  529.       Classes: array[0..0] of TRWCtlClass;     { Class list }
  530.     end;
  531.  
  532.     TCtlClassList contains a variable number of TRWCtlClass
  533.     records, the number of which is determined by the nClasses
  534.     field.
  535.  
  536.     PRWCtlClass = ^TRWCtlClass;
  537.     TRWCtlClass = record
  538.       fnInfo:  TFnInfo;                       { Info function }
  539.       fnStyle: TFnStyle;                      { Style function }
  540.       fnFlags: TFnFlags;                      { Flags function }
  541.       szClass: array[0..ctlClass-1] of Char;  { Class name }
  542.     end;
  543.  
  544.     Each control class in the DLL must have a corresponding
  545.     TRWCtlClass record in the TCtlClassList. The szClass field
  546.     contains the name with which the class was registered. For
  547.     example, if you called RegisterClass giving the class name as
  548.     'MYBUTTON', szClass must be 'MYBUTTON'.
  549.  
  550. The function variables Info, Style, and Flags--which correspond
  551. to the pointers TFnInfo, TFnStyle, and TFnFlags--are described in
  552. the following sections.
  553.  
  554.  
  555. 3.2      Info function
  556. ----------------------
  557.  
  558. The Info function is called by Resource Workshop to retrieve
  559. information about the control class, including the string to add
  560. to the control menu and the bitmap to add to the tool palette.
  561. The function returns a memory handle that can be allocated by
  562. GlobalAlloc. This handle must refer to memory that contains a
  563. TRWCtlInfo record.  Like ListClasses, the handle returned by Info
  564. is freed by Resource Workshop and should not be freed by the DLL.
  565. This function is called once by Resource Workshop upon loading
  566. the DLL.
  567.  
  568. Syntax:
  569.  
  570.     function Info: Handle; export;
  571.  
  572. Return value:
  573.  
  574.     Returns a handle to global memory containing a record of type
  575.     TRWCtlInfo.
  576.  
  577. Parameters:
  578.  
  579.     None.
  580.  
  581. Return value record:
  582.  
  583.     TRWCtlInfo has two parts:
  584.  
  585.     - A fixed-length part that provides information about the
  586.       control class in general.
  587.  
  588.     - A variable-length array of records, with each record
  589.       providing information about a particular type or subclass
  590.       of the control.
  591.  
  592.     Each control class can include several control types. For
  593.     example, Windows provides a BUTTON class that includes push
  594.     buttons, radio buttons, and check boxes. This variety can be
  595.     duplicated by your classes by providing two or more
  596.     TRWCtlType records in the TRWCtlInfo record.
  597.  
  598.     The following is the declaration of TRWCtlInfo:
  599.  
  600.     PRWCtlInfo = ^TRWCtlInfo;
  601.     TRWCtlInfo = record
  602.       wVersion:   Word;           { control version }
  603.       wCtlTypes:  Word;           { control types }
  604.       szClass:    array[0..ctlClass-1] of Char;
  605.                                   { control class name }
  606.       szTitle:    array[0..ctlTitle-1] of Char;
  607.                                   { control title }
  608.       szReserved: array[0..9] of Char;
  609.                                   { reserved for future use }
  610.       ctType:     array[0..ctlTypes] of TRWCtlType;
  611.                                   { control type list }
  612.     end;
  613.  
  614.     wVersion       The version number of the custom control
  615.                    library. The major version is in the
  616.                    high-order byte and the minor version in the
  617.                    low-order byte. For example, version 1.02 is
  618.                    $0102. This field is not used by Resource
  619.                    Workshop.
  620.  
  621.     wCtlTypes      The number of control sub-types defined in the
  622.                    ctType array.
  623.  
  624.     szClass        The name of the class as registered with
  625.                    Windows.  This is duplicated from the
  626.                    TCtlClassList record to retain upward
  627.                    compatiblity with the Windows custom control
  628.                    specificiation.
  629.  
  630.     szReserved     Space reserved for future expansion.  Must be
  631.                    cleared to null characters (#0).
  632.  
  633.     ctType         An array of sub-type description records of
  634.                    type TRWCtlType.
  635.  
  636.     The following is the declaration of TRWCtlType:
  637.  
  638.     PRWCtlType = ^TRWCtlType;
  639.     TRWCtlType = record
  640.       wType:   Word;                         { type style }
  641.       wWidth:  Word;                         { suggested width }
  642.       wHeight: Word;                         { suggested height }
  643.       dwStyle: LongInt;                      { default style }
  644.       szDescr: array[0..ctlDescr-1] of Char; { menu name }
  645.       hToolBit:  HBitmap;                    { toolbox bitmap }
  646.       hDropCurs: HCursor;              { drag and drop cursor }
  647.     end;
  648.  
  649.     wType          A user-defined value used to indicate the
  650.                    sub-type of the control.  This value is not
  651.                    used by Resource Workshop.
  652.  
  653.     wWidth         The default width for the control.  Resource
  654.                    Workshop will use this value if, for example,
  655.                    the control is created by dragging the icon
  656.                    from the tool palette.  wWidth is in dialog
  657.                    coordinates unless the most significant bit is
  658.                    set, in which case the value is in pixels. For
  659.                    example, a value of "32" is 32 in dialog
  660.                    coordinates, but the value "32 or $8000" is in
  661.                    pixels.
  662.  
  663.     wHeight        The default height for the control.  Resource
  664.                    Workshop will use this value if, for example,
  665.                    the control is created by dragging the icon
  666.                    from the tool palette.  wHeight is in dialog
  667.                    coordinates unless the most significant bit is
  668.                    set, in which case the value is in pixels. For
  669.                    example, a value of "32" is 32 in dialog
  670.                    coordinates, but the value "32 or $8000" is in
  671.                    pixels.
  672.  
  673.     wStyle         The default style Resource Workshop will use
  674.                    to create the Window.  This is the key field
  675.                    that you will use to distinguish one subtype
  676.                    from another.
  677.  
  678.     szDescr        The description of the control subtype.  This
  679.                    text is used by Resource Workshop to construct
  680.                    a menu item that the user can use to create an
  681.                    instance of your custom control.
  682.  
  683.     hToolBit       A handle to a bitmap which will be placed on
  684.                    the tool palette.  Resource Workshop requires
  685.                    the bitmap be a 22x22 black and gray bitmap
  686.                    containing a 2-pixel border that is white on
  687.                    the top and left and black on the bottom and
  688.                    right. You can use the bitmaps contained in
  689.                    BITBTN.RES as templates.
  690.  
  691.     hDropCurs      A cursor to be used while dragging the control
  692.                    from the tool palette.
  693.  
  694.  
  695. 3.3      Style function
  696. -----------------------
  697.  
  698. The Style function makes it possible for you to edit your custom
  699. control. You must first create an appropriate dialog box in
  700. Resource Workshop and then implement a Boolean function that
  701. displays that dialog box. Resource Workshop calls this function
  702. whenever you initiate a request to edit the custom control.
  703. Resource Workshop passes the function a handle to the window that
  704. is the parent of the dialog, a handle to memory containing the
  705. TRWCtlStyle record, and two function variables for string
  706. conversion.
  707.  
  708. Return value:
  709.  
  710.     The function must return true if the TRWCtlSytle record has
  711.     been modified; otherwise, it must return false.
  712.  
  713. Syntax:
  714.  
  715.     function Style(Window: HWnd; CtlStyle: THandle; StrToId:
  716.       TStrToId; IdToStr: TIdToStr): Bool; export;
  717.  
  718. Parameters:
  719.  
  720.     Window         A handle to the parent window of the dialog
  721.                    box displayed by this function.
  722.  
  723.     CtlStyle       A handle to global memory containing the
  724.                    TRWCtlStyle record to be edited.
  725.  
  726.     StrToId        A function variable that converts a string
  727.                    into a control ID for the wId field of
  728.                    TRWCtlStyle. This allows the user to enter the
  729.                    control ID using a constant identifier. This
  730.                    routine evaluates the string as an expression,
  731.                    returning the result.  The ID can be converted
  732.                    back into a string by calling IdToStr.
  733.  
  734.     IdToStr        A function variable that converts the control
  735.                    ID in the wId field of TRWCtlStyle to a string
  736.                    for editing. The ID can be converted back into
  737.                    a word by calling StrToId. This function
  738.                    variable allows the user to see the symbolic
  739.                    constant that represents the control ID
  740.                    instead of the word value.
  741.  
  742. CtlStyle record:
  743.  
  744.     The following is the record type referenced by the CtlStyle
  745.     memory handle:
  746.  
  747.       PRWCtlStyle = ^TRWCtlStyle;
  748.       TRWCtlStyle = record
  749.         wX:   Word;               { x origin of control }
  750.         wY:   Word;               { y origin of control }
  751.         wCx:  Word;               { width of control }
  752.         wCy:  Word;               { height of control }
  753.         wId:  Word;               { control child id }
  754.         dwStyle: LongInt;         { control style }
  755.         szClass: array[0..ctlClass-1] of Char;
  756.                                   { name of control class }
  757.         szTitle: array[0..ctlTitle-1] of Char;
  758.                                   { control text }
  759.         CtlDataSize: Byte;        { control data size }
  760.         CtlData: array[0..ctlDataLength-1] of Char;
  761.                                   { control data }
  762.       end;
  763.  
  764.       wX           The horizontal (X) location of the control in
  765.                    dialog coordinates.
  766.  
  767.       wY           The vertical (Y) location of the control in
  768.                    dialog coordinates.
  769.  
  770.       wCx          The width of the control in dialog
  771.                    coordinates.
  772.  
  773.       wCy          The height of the control in dialog
  774.                    coordinates.
  775.  
  776.       wId          The control's ID value.  This value must be
  777.                    converted to a string by calling IdToStr
  778.                    before being displayed for editing. It must be
  779.                    converted back into a word for storage by
  780.                    calling StrToId after editing.
  781.  
  782.       dwStyle      The style flags of the control.
  783.  
  784.       szClass      The class name of the control.
  785.  
  786.       szTitle      The title of the control.
  787.  
  788.       CtlDataSize  Windows allows controls in a resource file to
  789.                    have up to 255 bytes of control-defined data.
  790.                    This field indicates how much of that space is
  791.                    being used by the control.  The data is stored
  792.                    in CtlData.
  793.  
  794.       CtlData      This field holds up to 255 bytes of
  795.                    control-specific data.  The amount used must
  796.                    be recorded in the CtlDataSize field.  The use
  797.                    of this data area is user-defined.
  798.  
  799. When you save your project, Resource Workshop saves the CtlData
  800. array into the .RC or .RES file.
  801.  
  802. To enable a custom control to access this array from within your
  803. program at run time, lParam of the WM_CREATE message points to a
  804. CREATESTRUCT data structure. The CREATESTRUCT structure contains
  805. a field, lpCreateParams, that is a pointer to the extra data you
  806. stored in the CtlData array. If the pointer is nil, there is no
  807. CtlData.
  808.  
  809. The CtlDataSize variable is not available to your program. To
  810. make the size data accessible to your program, the CtlData array
  811. should either contain a fixed amount of data, or its first byte
  812. should contain the length of the data.
  813.  
  814. The Style function first converts the ID to a string by passing
  815. the numerical ID value to IdToStr. The Style function then
  816. displays the string in the dialog box.
  817.  
  818. If the user changes the string that's returned by IdToStr, the
  819. Style function verifies the string by passing it to StrToId,
  820. which determines if the string is a valid constant expression. If
  821. StrToId returns a zero in the low word, the ID is illegal and is
  822. displayed in the dialog box so the user can change it to a valid
  823. ID. If StrToId is successful, it returns a nonzero value in the
  824. low word and the ID in the high word.
  825.  
  826.  
  827. 3.4      Flags function
  828. -----------------------
  829.  
  830. The Flags function is used by Resource Workshop to translate the
  831. style of a control into text.  Resource Workshop inserts the text
  832. into the .RC file being edited.  The function must only convert
  833. the values unique to the control.  For example, if you were
  834. creating a Flags function for the Windows button class, you would
  835. only examine the lower sixteen bits of Flags and translate them
  836. into one of the bs_XXXX constants.
  837.  
  838. Return value:
  839.  
  840.     Returns the number of bytes copied into the destination
  841.     string. Returns 0 if the Flags word is not valid or the
  842.     string exceeds MaxString in length.
  843.  
  844. Syntax:
  845.  
  846.     function Flags(Flags: LongInt; Style: PChar; MaxString:
  847.       Word): Word;
  848.  
  849.   Parameters:
  850.  
  851.     Flags          The style of the control to be translated into
  852.                    text.  This field is derived from the dwStyle
  853.                    field of the TRWCtlStyle record passed to the
  854.                    Style function variable.
  855.  
  856.     Style          The location to write the translated text.
  857.  
  858.     MaxString      The maximum number of bytes the Flags function
  859.                    can write into Style.
  860.                    
  861.  
  862.            ========= END OF FILE CUSTCNTL.RW =========
  863.