OVERVIEW_DUAL_FUNC

Dual-Mode Functions

Description:

    DUAL-Mode functions have been designed to work in either
    TEXT mode or GUI mode.  Text mode is selected by calling
    DC_GUI(.f.) and GUI mode is selected by calling DC_GUI(.t.).
   
    Functions in the DCLIPX.DLL dynamic-link library all start
    with the prefix DC_.  The DCLIPX.DLL file is one of the
    libraries that are included with the dCLIP++ Application
    Development System, and your eXPress++ system is fully
    compatible with dCLIP++ in the event that at some time you
    wish to upgrade and utilize the dCLIP++ design tools.
   

OVERVIEW_GENERAL

General Functions

Description:

    General functions are those which have been designed to work
    identically in either TEXT mode or GUI mode.  These functions
    do not create any output to the screen in either mode,
    therefore they can be used freely without regard to the
    screen mode, DC_GUI().
   
    Functions in the DCLIPX.DLL dynamic-link library all start
    with the prefix DC_.  The DCLIPX.DLL file is one of the
    libraries that are included with the dCLIP++ Application
    Development System, and your eXPress++ system is fully
    compatible with dCLIP++ in the event that at some time you
    wish to upgrade and utilize the dCLIP++ design tools.
   

OVERVIEW_GUI_FUNC

GUI Functions/Classes

Description:

    GUI functions are designed to work only in GUI mode.  When any of
    these functions are used they ignore the setting of the DC_Gui()
    flag.
   

OVERVIEW_TEXT_FUNC

Text Mode Functions/Classes

Description:

    Text-Mode functions are designed to work only in TEXT mode.
    When any of these functions are used they ignore the setting of
    the DC_Gui() flag and require that the SetAppWindow() be a CRT
    window (XbpCrt Class).
   

dc_abigelem()

Return element of longest string in an array

Syntax:

    DC_ABigElem ( < aArray >, ;
                  [@< nLength >] ) - > nElement
   

Arguments:

   < aArray > is the name of any single-dimensional array that is
   fill with character strings.
   
   @< nLength > is the name of a variable to place the length
   of the item returned.
   

Returns:

    A number equivalent to the element of the array with the
    longest string.
   

Description:

    DC_ABIGELEM() will return the element number of the longest
    string in a single-dimensional array.
   

Examples:

    . nLength := 0
    . aTest := { 'abc','abcdef','abcde','abcd' }
    . ? DC_ABIGELEM( aTest, @nLength )
    2
    . ? nLength
    6
   

Source/Library:

  _DCARRAY.PRG, DCLIP1.DLL

dc_achoice()

A Dual-Mode replacement for ACHOICE()

Syntax:

   DC_AChoice ( < nTop >, < nLeft >, < nBottom >, < nRight >, ;
                < aMenuItems >, ;
                [< aSelItems >], ;
                [< cUserFunc > | < bUserFunc >], ;
                [< nInitialItem >], ;
                [< nWindowRow >], ;
                [< aButtons >], ;
                [< aOptions >], ;
                [< aHelpCodes >], ;
                [< aMenu >], ;
                [< lAttachMenu >] ) - > nPosition
   

Arguments:

   < nTop >, < nLeft >, < nBottom >, < nRight > are the screen
   coordinates.
   
   < aMenuItems > is an array of character strings to include
   in the pick-list.
   
   < aSelItems > is an array of logical values.  There is one
   element in this optional array for each element in
   < aMenuItems >.  Each element in < aSelItems > that is a
   .TRUE. will make the item in the window a "selectable"
   item, otherwise it will be a non-selectable item and will
   be displayed in "grayed" form.
   
   < cUserFunc > | < bUserFunc > is the name of an optional User-Defined
   function to call on exception keystrokes.  See the Clipper
   documentation of ACHOICE() for more information on how to use
   a UDF.  If the parameter is passed as a character string then
   the function must be a PUBLIC, not STATIC function.
   
   < nInitialItem > is the item to high-light in the window on
   startup.
   
   < nWindowRow > is the item to display as the first item in
   the pick-list.
   
   < aButtons > is an array of mouse-keys that conforms to the
   specification for DC_MOUSEKEY().   See DC_MOUSEKEY() for
   more information.
   
   < aOptions > is a multi-dimensional array of the following
   options:
   
   Element  Type   Description
   -------  ----   ----------------------------------------------
     [1]     L     If .TRUE. will display a scrollbar and box
                   around the menu items.
     [2]     A     A sub-array of colors to use if element [1] is
                   .FALSE.  If passed as a NIL then the Clipper
                   default colors will be used.
   
                   Element  Type  Description
                  -------  ----  ----------------------------
                    [1]       C   Menu items color
                    [2]       C   Select bar color
                    [3]       C   Frame/scrollbar color
                    [4]       C   Spare
                    [5]       C   Unselectable items color
   
     [3]     C     Title on top of box.  Default is none.
     [4]     L     If .TRUE. then the operator will be allowed to
                   drag the box with the mouse. Default is .FALSE.
     [5]     L     If .TRUE. then the display will be restored
                   upon exit, otherwise it will remain.
     [6]     L     If .TRUE. then the frame, scroll-bar and title
                   will be painted, otherwise only the items will
                   be painted.
     [7]     L     If .TRUE. then after painting the scroll-bar,
                   items and frame, DC_ACHOICE() will exit without
                   waiting for a key or mouse-click.
   
   < aHelpCodes > is an array of character string HELP CODES.
   There is one element in this optional array for each element in
   < aMenuItems >.  The HELP CODE will be passed on to the
   DC_HelpF1() function for context-specific help if the operator
   presses F1 on a selected item.
   
   < aMenu > is an array defining a Top-Bar/Pull-Down menu. This
   array must conform to the specification for the array passed
   to the DC_MENUMAIN() function.   This Top-Bar menu will be
   painted at the screen coordinates defined in the menu if
   < lAttachMenu > is .FALSE. or directly attached to the top of
   the pick-list window if < lAttachMenu > is .FALSE. (default).
   The menu will be energized if the operator presses a key
   matching one of the hightlighted characters in the menu, or
   if the mouse is clicked on one of the top-bar menu items.
   The menu array must contain code-blocks for each menu item
   to execute functions based on the menu selection.  See
   DC_MENUMAIN() for more information.
   

Description:

    DC_ACHOICE() is a Dual-mode replacement for AChoice().  When
    the GUI flag is ON, DC_ACHOICE() functions similiar to
    AChoice() except that it is displayed in GUI mode.  When the
    GUI flag is OFF, DC_ACHOICE() functions identical to ACHOICE()
    except it is also activated by a mouse.  The left button of the
    mouse is used to select the item in the window.  The right button
    or double-clicking works  identical to the ENTER key.
   
    In TEXT mode, Hot keys can be activated by passing an array of
    screen coordinates (mouse-buttons) and key definitions.
   
    In TEXT mode, an options array is used to define scroll-bars,
    colors, exit options, title, drag options, etc.
   
    An optional array of Help-Codes may be passed for context-
    specific help on any selected item with the F1 key.
   

Examples:

    local nChoice
    local aButtons := { { 17,13,17,18,'C'},;
                        { 18,13,18,18,'D'},;
                        { 19,13,19,18,'M'} }
    local aDir := directory()
    set key asc('C') to myfunc
    set key asc('D') to myfunc
    set key asc('M') to myfunc
    cls
    @5,10 to 20,30
    @16,11 to 16,29
    @17,13 say 'Copy'
    @18,13 say 'Delete'
    @19,13 say 'Move'
    aDir := dc_aconvert( aDir )
    nChoice := DC_ACHOICE( 6,11,15,29,aDir[1],,,,,aButtons )
    set key asc('C') to
    set key asc('D') to
    set key asc('M') to
    return
   
    function myfunc
   
    @ 22,10 say ''
    do case
      case lastkey() = asc('C')
        ?? 'C button pressed'
      case lastkey() = asc('D')
        ?? 'D button pressed'
      case lastkey() = asc('M')
        ?? 'M button pressed'
    endcase
    return nil
   

Source/Library:

  _DCACHOI.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_dbchoice()
   dc_readapick()
   dc_apick()

dc_acompare()

Compare two arrays

Syntax:

   DC_ACompare ( < aArray1 >, ;
                 < aArray2 > ) - > lStatus
   

Arguments:

   < aArray1 > and < aArray2 > are the arrays to compare.
   

Returns:

    A logical .TRUE. if the arrays are identical, .FALSE. otherwise.
   

Description:

    DC_ACOMPARE() is used to test the contents of two arrays to
    determine if they are identical.
   

Examples:

     PROCEDURE Xtest()
   
     LOCAL aArray1, aArray2, aArray3
   
     aArray1 := { 1,2,3 }
     aArray2 := { '1',2,3, }
     aArray3 := { 1,2,3 }
   
     DC_Gui(.t.)
   
     DC_MsgBox( { 'Is aArray1 equal to aArray2?', ;
                  '',;
                  DC_ACOMPARE(aArray1,aArray2) } )
   
     DC_MsgBox( { 'Is aArray1 equal to aArray3?', ;
                  '',;
                  DC_ACOMPARE(aArray1,aArray3) } )
   
   
     RETURN
   

Source/Library:

  _DCARRAY.PRG/.OBJ, DCLIPX.LIB

dc_aconvert()

Convert a Ragged array to a Parallel array and vice-versa

Syntax:

   DC_AConvert ( < aInput > ) - > aOutput
   

Arguments:

   < aInput > is a Parallel Symmetrical array or Ragged Symmetrical
   array.
   
   Example of a "Parallel Symmetrical array":
   
                     Type  Contents
   
        aStru[1]       A
          aStru[1,1]   C   CUST_NAME
          aStru[1,2]   C   SHIP_DATE
          aStru[1,3]   C   BALANCE
          aStru[1,4]   C   PRINT_FLAG
        aStru[2]       A
          aStru[2,1]   C   C
          aStru[2,2]   C   D
          aStru[2,3]   C   N
          aStru[2,4]   C   L
        aStru[3]       A
          aStru[3,1]   C   25
          aStru[3,2]   C   8
          aStru[3,3]   C   9
          aStru[3,4]   C   1
        aStru[4]       A
          aStru[4,1]   N   0
          aStru[4,2]   N   0
          aStru[4,3]   N   2
          aStru[4,4]   N   0
   
   
    Example of a "Ragged Symmetrical array":
   
                              Type  Contents
   
        aStru[1]       A
          aStru[1,1]   C   CUST_NAME
          aStru[1,2]   C   C
          aStru[1,3]   C   25
          aStru[1,4]   N   0
        aStru[2]       A
          aStru[2,1]   C   SHIP_DATE
          aStru[2,2]   C   D
          aStru[2,3]   C   8
          aStru[2,4]   N   0
        aStru[3]       A
          aStru[3,1]   C   BALANCE
          aStru[3,2]   C   N
          aStru[3,3]   C   9
          aStru[3,4]   N   2
        aStru[4]       A
          aStru[4,1]   C   PRINT_FLAG
          aStru[4,2]   C   L
          aStru[4,3]   C   1
          aStru[4, ]   N   0
   

Returns:

    An array whose elements contain the same information as the
    input array but are in "inverted" order.
   

Description:

    DC_ACONVERT() is used to changed the format of a symmetrical
    array from "Ragged" to "Parallel" or vice-versa.  This function
    is handy when information in an array may not be stored in a
    required format. For example, it is not easy to perform
    "pick-list" operations from "Ragged" arrays or to AEVAL()
    "Parallel" arrays.
   

Examples:

    PROCEDURE XTest()
   
    LOCAL aRaggedDir, aParallelDir, nChoice
   
    // Converting a Ragged array to a Parallel array
   
    aRaggedDir := Directory()
    aParallelDir := DC_ACONVERT( aRaggedDir )
   
    DC_Gui(.t.)
   
    nChoice := DC_Achoice( 10,10,20,40, aParallelDir[1] )
   
    DC_MsgBox( 'The size of ' + aParallelDir[1,nChoice] + ' is ' + ;
                Str( aParallelDir[2,nChoice] ) )
   
    RETURN
   

Source/Library:

  _DCARRAY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_areverse()

dc_addcargo()

Add cargo to the GetList

Syntax:

   DC_AddCargo ( < GetList >, ;
                 < xCargo > ) - > GetList
   

Arguments:

   < GetList > is the GetList array.
   
   < xCargo > can be one of several numeric values or an array.
   
     xCargo        Description
     ------       ----------------------------------------
      101          Force this GET to validate
      102          Display Pick-list pointer icon (arrow)
     {103,bBlock}  Pre-Evaluate Code-Block
     {104,bBlock}  Post-Evaluate Code-Block
     {105,aMsg}    Message to display on screen
      106          Protect this GET from editing
      107          Capitalize first character of each word
     {108,aData}   SAY prompt and coordinates
   

Returns:

    A pointer to the <þGetListþ> passed to DC_ADDCARGO().
   

Description:

    DC_ADDCARGO() is used to add cargo to the an array that
    is contained in the CARGO instance variable of the last
    GET in a GetList array.
   
    DC_READMODAL() automatically looks at the information in
    CARGO to give added functionality to the GET system.
    CARGO is used to store array pointers, screen SAY
    information and other GET options.
   

Examples:

    #include "dcget.ch"
   
    LOCAL GetList := {}, aData, i
   
    use 
    aData := Array(Fcount())
    FOR i := 1 TO LEN( aData )
      aData[i] := FieldGet(i)
    NEXT
    DC_ReadWindow( { 10, 10, 20, 60 } )
    FOR i := 1 TO LEN(aData)
   
      DC_GetDevOut( i, 12, PadL(Field(i),10), )
      SetPos( Row(), Col()+1 )
      AAdd( GetList,_GET_(aData[i],"aData[i]",,,) )
      DC_GetDisplay( GetList )
   
      /* -- Add array element pointer -- */
      GetList := DC_ADDCARGO(GetList,-1*i)
   
      /* -- Add SAY Prompt and location -- */
      GetList := ;
         DC_ADDCARGO(GetList,{ 108, { i, 12, PadL(Field(i),10) }})
   
      /* -- Add CAPFIRST flag -- */
      GetList := DC_ADDCARGO(GetList,107)
   
    NEXT
    DC_ReadModal( GetList,,aReadArea )
    RETURN nil
   

Source/Library:

  _DCGETSY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readmodal()
   dc_readbox()

dc_addrec()

Append a new record and lock the record

Syntax:

    DC_AddRec ( [< nWaitTime >], ;
                [< lDisplayError >], ;
                [< nAppendMode >] ) - > lStatus
   

Arguments:

   < nWaitTime > is the number of seconds to wait for the system to
   return a lock before returning the status or the error message.
   (0 = wait forever).
   
   < lDisplayError > if .true. will display an operator error
   message if the record cannot be locked. (default) or if .false.
   will not display an error message to the operator.
   
   < nAppendMode > is a number from 0 to 2 (0 is the default) to
   establish the mode for reusing deleted or blank records, if
   they exist, or appending a new record.  See DC_APPENDMODE().
   

Returns:

    A logical .TRUE. if the record is successfully locked.
   

Description:

    The function of DC_ADDREC() is dependent on the APPEND MODE of
    operation that was previously selected by the DC_APPENDMODE()
    function.
   
    If the Append Mode is 0 (default), then DC_ADDREC() will always
    append a Blank record.
   
    If the Append Mode is 1, then DC_ADDREC() will first try to
    locate any existing Blank record in the database.  If a Blank
    record is found, the record pointer will be set to the found
    record and the record will be locked.  This mode functions
    differently based on whether or not the current work area
    has an index selected.  If an index is selected, then it is
    assumed that blank records will always appear at the TOP of
    the database so only the first record is tested, otherwise
    the entire database will be search for a blank record.
   
    If the Append Mode is 2, then DC_ADDREC() will first try to
    locate any existing record that is marked for deletion.  If
    a deleted record is found, the record pointer will be set
    to the found record, the record will be recalled (undeleted),
    all fields will be blanked, and the record will be locked.
   

Examples:

    dc_appendmode(1)  // reuse blank records
    use sales
    if DC_ADDREC()
      replace date with date()
    else
      break
    endif
   

Source/Library:

  _DCLOCK.PRG, DCLIP1.DLL

See Also:

   dc_reclock()
   dc_filock()
   dc_appendmode()
   APPEND
   LOCK
   UNLOCK

dc_addsetkeys()

Convert all SET KEYS to DCHOTKEY commands

Syntax:

    DC_AddSetKeys( < aGetList > ) - > aGetList
   

Arguments:

   < aGetList > is the GetList array that will be passed to DC_ReadGUI().
   

Returns:

    A GetList array with all hotkeys added.
   

Description:

    DC_ADDSETKEYS is used to read the current SET KEYS and add them
    to the GetList as DCHOTKEY commands.
   

Examples:

   FUNCTION XTest()
   
   LOCAL GetList := {}, dDate := Date(), nNumber := 0
   
   SET KEY -2 TO DC_PopDate()
   SET KEY -3 TO DC_PopCalc()
   
   @ 1,1 DCSAY '  Enter a Date' GET dDate
   @ 3,1 DCSAY 'Enter a Number' Get nNumber
   
   @ 5,1 DCSAY 'Press F3 for a Calendar' SAYSIZE 30
   @ 6,1 DCSAY 'Press F4 for a Calculator' SAYSIZE 30
   
   DC_ADDSETKEYS(GetList)
   
   DCREAD GUI FIT ADDBUTTONS
   
   RETURN nil
   

Source/Library:

  _DCFUNCT.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readgui()
   DCHOTKEY

dc_alert()

A Dual-Mode replacement for Clipper's ALERT() function

Syntax:

   DC_Alert ( < cText >, ;
              < aMenuItems >, ;
              [< cColorString >], ;
              [< lJustify >], ;
              [< aMenuId >], ;
              [< cMenuName >], ;
              [< nChoice >], ;
              [< aFonts >] ) - > nChoice
   

Arguments:

   < cText > is the message to place in the alert box.  Use
   semicolons in the text to separate lines of text.
   
   < aMenuItems > is an array of menu choices.  The character
   following the '~' character will be highlighted.
   
   < cColorString > is an optional color string containing
   exactly 4 colors separated by commas:
   
    (1) box and message.
    (2) unselected menu items.
    (3) hot-key character of each unselected menu item
    (4) selected menu item
   
   < lJustify > if .TRUE. will left-justify the message items.
   Default is .FALSE.
   
   < aMenuId > - An optional array of unique Menu ID codes (up to 8
   characters) for each menu item in < aItems >.  This array is
   needed to enable the PERSISTENT MENU SELECTION feature.  See
   DC_MenuPull() for more information.
   
   < cMenuName > - An optional parameter with a "unique" name for
   this menu.  This name is needed to enable the PERSISTENT MENU
   SELECTION feature.  See DC_MenuPull() for more information.
   
   < nChoice > is the default menu selection.
   
   < aFonts > is a 2-element array containing the Font Compound Name
   for the buttons and the text.  Element 1 is the button font and
   element 2 is the text font.  This parameter is used in GUI mode
   only.
   

Returns:

    A number equal to the menu choice.  Returns 0 if user
    presses ESCape.
   

Description:

    DC_ALERT() is a Dual-mode replacement for Alert().  When
    the GUI flag is ON, DC_ALERT() functions similiar to
    Alert() except that it is displayed in GUI mode.  When the
    GUI flag is OFF, DC_ALERT() functions identical to Alert()
    except it is also activated by a mouse.  The left button of the
    mouse is used to select the item in the window.
   

Notes:

   The foreground and background color of the GUI alert box is
   preset by the function DC_AlertColor().
   

Examples:

    PROCEDURE XTest()
   
    LOCAL nChoice
   
    DC_Gui(.t.)
   
    nChoice := DC_ALERT( "The printer is not ready",;
              { 'Retry','Abort','Output to a file' } )
   
    DC_MsgBox( 'You chose ' + Str(nChoice) )
   
    RETURN
   

Source/Library:

  _DCMENU2.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_msgbox()
   dc_guialert()

dc_andbits()

A logical AND of two bytes

Syntax:

   DC_AndBits( < nNum1 >, ;
               < nNum2 > ) - >nResult
   

Arguments:

   < nNum1 > and < nNum2 > are numeric values from 0 to 255.
   

Returns:

    A numeric value from 0 - 255
   

Description:

   DC_ANDBITS() will produce the result of logically ANDing two bytes.
   

Source/Library:

  _DCAND.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_bittest()
   dc_xorbits()

dc_apick()

A dialogue for choosing a item from an array pick list.

Syntax:

   DC_APick ( [< nTop >], [< nLeft >], < nWidth >, < nHeight >, ;
              < aMenuItems >, ;
              [< acHeader >], ;
              [< anWidth >], ;
              [< cTitle >], ;
              [< anTag >], ;
              [< aTagColor >], ;
              [< bHandler >], ;
              [< nStart >], ;
              [< cFontName >], ;
              [< oParent >], ;
              [< oOwner >], ;
              [< lCenter >], ;
              [< lMenu >], ;
              [< lNoVScroll >], ;
              [< lNoHScroll >], ;
              [< aPres >] ) - > nChoice
   

Arguments:

   < nTop >, < nLeft > are the starting coordinates.  These are text-
   base coordinates.  These parameters are not required if the
   < lCenter > parameter is used.
   
   < nWidth > and < nHeight > are the width and height of the window
   in text-based coordinates.
   
   < aMenuItems > is an array of character strings to include
   in the pick-list.  This may be a single-dimension array or a
   multi-dimension array.
   
   < acHeader > is the heading to place above each column.  If
   < aMenuItems > is a single-dimension array, then there is only 1
   header, so < acHeader > is a character string.  If < aMenuItems >
   is a multi-dimension array, then < acHeader > is an array of
   character strings, 1 for each column.
   
   < anWidth > is the width of the column(s).  If aMenuItems > is a
   single-dimension array, then there is only 1 width, so < anWidth >
   is a numeric value.  If < aMenuItems > is a multi-dimension array,
   then < anWidth > is an array of numeric values, 1 for each column.
   
   < cTitle > is the title to place at the top of the window.
   
   < anTag > is an array of logical elements or a single numeric
   value.  If < anTag > is an array, it must be the same length as
   the array being browsed and must contain logical values.  When
   the user double-clicks a browse row, the corresponding element
   of < anTag > will be toggled.  If < anTag > is a numeric value, then
   it is a pointer to the column of < aMenuItems > that contains
   logical tags.
   
   < aTagColor > is used in conjunction with < anTag > to select the
   color for the rows that are tagged.  This is a 2-element array
   consisting of a foreground and background color.  The default
   is { GRA_CLR_WHITE, GRA_CLR_BLUE }.
   
   < bHandler > is a SPARE.
   
   < nStart > is the starting element in the browse.
   
   < cFontName > is the font to use for the browse.
   
   < oParent > is the parent object to create the browse.  If no
   parameter is passed, a dialog window will be created.
   
   < oOwner > is the owner object of the browse.  If no parameter is
   passed, the owner will be the same as the parent.
   
   < lCenter > if .TRUE. will center the browse dialog on the desktop.
   
   < lMenu > if .TRUE. will enable "menu mode".  This allows the
   operator to press keyboard keys that match the first letter of
   each array item to select the item.
   
   < lNoVScroll > if .TRUE. will suppress the vertical scroll bar.
   The default is .FALSE.
   
   < lNoHScroll > if .TRUE. will suppress the horizontal scroll bar.
   The default is .FALSE.
   
   < aPres > is an array of presentation parameters that must conform
   to the presParam specifications for the XbpBrowse() class.
   

Returns:

   A Numeric Value equivalent to the selected row.
   

Description:

   DC_APick() is used to display a browse-style picklist of an
   array.
   

Examples:

   FUNCTION XTest()
   
   LOCAL aDir := Directory(), i, aHeaders, aWidths
   
   FOR i := 1 TO Len(aDir)
     ASize(aDir[i],5)
     aDir[i,5] := .f.
   NEXT
   
   aHeaders := { 'File Name', 'File Size', 'File Date', 'File Time' }
   
   aWidths := { 10,10,10,10 }
   
   nChoice := DC_APick ( , , 50, 10, aDir, ;
              aHeaders, aWidths, 'Disk Directory', 5, ;
              { GRA_CLR_WHITE, GRA_CLR_RED }, ;
              nil, nil, '8.Terminal', nil, nil, .t. )
   
   RETURN nChoice
   

Source/Library:

  _DCACHOI.PRG/.OBJ, DCLIPX.LIB

See Also:

   DCAPICK
   dc_achoice()

dc_appendmode()

Set the default mode of operation for DC_AddRec()

Syntax:

    DC_AppendMode ( < nMode > ) - > nOldMode
   

Arguments:

   < nMode > is a number designating the desired append mode.
   
   If the Append Mode is 0 (default), then DC_ADDREC() will always
   append a Blank record.
   
   If the Append Mode is 1, then DC_ADDREC() will first try to
   locate any existing Blank record in the database.  If a Blank
   record is found, the record pointer will be set to the found
   record and the record will be locked.  This mode functions
   differently based on whether or not the current work area
   has an index selected.  If an index is selected, then it is
   assumed that blank records will always appear at the TOP of
   the database so only the first record is tested, otherwise
   the entire database will be search for a blank record.
   
   If the Append Mode is 2, then DC_ADDREC() will first try to
   locate any existing record that is marked for deletion.  If
   a deleted record is found, the record pointer will be set
   to the found record, the record will be recalled (undeleted),
   all fields will be blanked, and the record will be locked.
   

Returns:

    A numeric value representing the current append mode.
   

Description:

    DC_APPENDMODE() is used to establish the default operation of
    the DC_ADDREC() function.  Depending on the mode selected
    DC_ADDREC() will attempt to reuse blank records or deleted
    before appending a new, blank record.
   

Examples:

    use sales
    set index to month
    DC_APPENDMODE(1)  // re-use blank records
    if dc_addrec()
      replace date with date()
    else
      break
    endif
   

Source/Library:

  _DCLOCK.PRG, DCLIP1.DLL

See Also:

   dc_addrec()

dc_appevent()

Post an Event Loop

Syntax:

    DC_AppEvent( @< lOk >, ;
                  < nExitEvent >, ;
                  < nDelay > ) - > nLastEvent
   

Arguments:

   @< lOk > is an optional logical value (passed by reference).
   DC_AppEvent() will exit and return when this value is set to
   .FALSE.
   
   < nExitEvent > is an optional numeric value.  DC_AppEvent() will
   exit and return when the next event in the event queue is
   equal to this value.  < nExitEvent > defaults to 0, meaning that
   the loop will exit when no more events are in the event queue.
   
   < nDelay > is the amount of delay to use when DC_AppEvent() calls
   the AppEvent() function.  This defaults to 0, meaning that
   event loop will not exit until an event occurs.  If < nDelay >
   is any value greater than 0, then this is amount of delay before
   the AppEvent() function exits.  < nDelay > should usually be set
   to a value of .01 when using DC_AppEvent() to process events
   while still processing other code.  See the example.
   

Returns:

    A numeric value equal to the last event processed in the loop.
   

Description:

    DC_APPEVENT() is a handy function that creates an event loop for
    processing events.  Unlike the Xbase++ AppEvent() function,
    DC_APPEVENT() contains a DO..WHILE loop that processes events as
    a single function call.
   

Examples:

   /*
   This example uses DC_APPEVENT() to abort a COPY TO process.
   */
   
   #include 'dcdialog.ch'
   
   FUNCTION XTest()
   
   LOCAL Getlist := {}, oProgress, oDialog, lOk := .t., oButton, ;
         nEvent, mp1, mp2, oXbp
   
   USE COLLECT VIA DBFNTX NEW SHARED
   
   @ 2,5 DCSAY 'Exporting Data to JUNK.DBF'
   
   @ 4,5 DCPROGRESS oProgress ;
          SIZE 55,1.5 ;
          MAXCOUNT RecCount() COLOR GRA_CLR_BLUE
   
   @ 4,65 DCPUSHBUTTON  CAPTION '&Cancel' ;
     ACTION {||lOk:=.f.} OBJECT oButton ;
     SIZE 8,1.5
   
   DCREAD GUI TITLE 'My Test Dialog' ;
      PARENT @oDialog ;
      FIT ;
      EXIT
   
   oDialog:show()
   
   COPY TO junk WHILE _Progress( oProgress, @lOk )
   
   oButton:SetCaption('&Ok')
   DC_APPEVENT( @lOk )
   
   oDialog:Destroy()
   CLOSE ALL
   
   RETURN nil
   
   /* ----------------- */
   
   STATIC FUNCTION _Progress ( oProgress, lOk )
   
   DC_GetProgress( oProgress, COLLECT->(RecNo()) )
   DC_Pause(.3)
   DC_APPEVENT( @lOk, 0, .01 )
   
   RETURN lOk
   

Source/Library:

  _DCGETBX.PRG/.OBJ, DCLIPX.LIB

dc_appeventdefine()

Translate AppEvent() value to DEFINE value

Syntax:

   DC_AppEventDefine( < nEvent > ) - > cDefinition
   

Arguments:

   < nEvent > is the AppEvent() to translate.
   

Returns:

    A Character string.
   

Description:

    DC_APPEVENTDEFINE() returns a character string that contains
    the DEFINITION name for the AppEvent() value.  These defines are
    contained in APPEVENT.CH.
   
    This is a handy debugging function that can be used in event
    loops to display events as they are occurring like so:
   
    DO WHILE nEvent # xbeP_None
      nEvent := AppEvent( @mp1, @mp2, @oXbp )
      ? DC_APPEVENTDEFINE( nEvent )
      oXbp:HandleEvent( nEvent, mp1, mp2 )
    ENDDO
   

Examples:

    #include 'appevent.ch'
   
    PROCEDURE XTest()
   
    DC_Gui(.t.)
   
    DC_MsgBox( { DC_APPEVENTDEFINE( xbeP_Close ), ;
                 DC_APPEVENTDEFINE( xbeP_Resize ), ;
                 DC_APPEVENTDEFINE( xbeP_Activate ) } )
   
    RETURN
   

Source/Library:

  _DCPUTK.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_keytran()
   dc_appkeydefine()

dc_appkeydefine()

Translate AppEvent() keyboard value to DEFINE value

Syntax:

   DC_AppKeyDefine( < nKey > ) - > cDefinition
   

Arguments:

   < nKey > is the AppEvent() value of the key to translate.
   

Returns:

    A Character string.
   

Description:

    DC_APPKEYDEFINE() returns a character string that contains the
    DEFINITION name for the AppEvent() a keyboard value.  These
    defines are contained in APPEVENT.CH.
   
    This is a handy debugging function that can be used in event
    loops to display events as they are occurring like so:
   
    DO WHILE nEvent # xbeP_None
      nEvent := AppEvent( @mp1, @mp2, @oXbp )
      IF nEvent = xbeP_Keyboard
        ? DC_APPKEYDEFINE( mp1 )
      ENDIF
      oXbp:HandleEvent( nEvent, mp1, mp2 )
    ENDDO
   

Examples:

    #include 'appevent.ch'
   
    PROCEDURE XTest()
   
    DC_Gui(.t.)
   
    DC_MsgBox( { DC_APPKEYDEFINE( xbeK_ALT_M ), ;
                 DC_APPKEYDEFINE( xbeK_ENTER ), ;
                 DC_APPKEYDEFINE( xbeK_INS ) } )
   
    RETURN
   

Source/Library:

  _DCPUTK.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_keytran()
   dc_appeventdefine()

dc_ar2str()

Convert a multidimensional array to a string

Syntax:

   DC_Ar2Str ( < aArray > ) - > cString
   

Arguments:

   < aArray > is any multidimenstional array.
   

Returns:

    A character string.
   

Description:

    DC_Ar2Str() will convert the contents of any multi-dimensional
    array to a string for later restoring with DC_Str2Ar().  The
    string may then be saved to a file or to a character or memo
    type database field.  This set of functions is an alternative
    to using the Xbase++ functions Var2Bin() and Bin2Var() because
    they will create a runtime error if the array contains code
    blocks with non-persistent data.
   
    If the array contains code blocks, the code blocks will be
    saved and restored provide that they contain persistent data.
    Any code block that contains non-persistent data will be
    saved as a NIL.
   
    If the array contains pointers to objects, they pointers will
    be saved as a NIL.
   

Examples:

    PROCEDURE XTest()
   
    LOCAL aDir
   
    aDir := Directory()
   
    USE dirs
    APPEND BLANK
    REPL DIRS->array WITH DC_Ar2Str(aDir)
   
    aDir := DC_Str2Ar(DIRS->array)
    DC_ArrayView(aDir)
   
    RETURN
   

Source/Library:

  _DCASAVE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_str2ar()
   dc_asave()

dc_arestore()

Restore a multidimensional array from a binary file

Syntax:

   DC_ARestore ( < cFileName > ) - > aArray
   

Arguments:

   < cFileName > is the name of the binary file that was previously
   created with DC_ASAVE().
   

Returns:

    A multidimensional array if the array file was a valid file,
    otherwise returns a NIL.
   

Description:

    DC_ARESTORE() will create an multidimensional array from the
    contents of a binary file that was created with DC_ASAVE().
   
    If the array contains code blocks, the code blocks will be
    saved and restored provide that they contain persistent data.
    Any code block that contains non-persistent data will be
    restored as a NIL.
   
    If the array contains pointers to objects, they pointers will
    be restored as a NIL.
   

Examples:

    PROCEDURE XTest()
   
    LOCAL aDir1, aDir2
   
    DC_Gui(.t.)
   
    aDir1 := Directory()
    dc_asave( aDir1, 'ADIR.ARX' )
    aDir2 := DC_ARESTORE( 'ADIR.ARX' )
   
    DC_Achoice( 5,10,20,30, DC_AConvert( aDir2 )[1] )
   
    RETURN
   

Source/Library:

  _DCASAVE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_asave()
   RESTORE ARRAY

dc_areverse()

Reverse all elements in an array

Syntax:

    DC_AReverse ( < aArray > ) - > aNewArray
   

Arguments:

   < aArray > is the name of the array to reverse.
   

Returns:

    An array of the same length as the original array.
   

Description:

    DC_AREVERSE() is used to sort all the elements of an array
    in reverse order from the original array.
   

Examples:

    myArray :=  { 1, 2, 'test', .t. }
   
    outArray := DC_AREVERSE( myArray )
   
    // contents of outArray :  { .t., 'test', 2, 1 }
   

Source/Library:

  _DCARRAY.PRG, DCLIP1.DLL

See Also:

   dc_aconvert()

dc_array_r()

Create a multi-dimensional array from an array text file

Syntax:

   DC_Array_Read ( < cArrayFile > ) - > aArray
   

Arguments:

   < cArrayFile > is the name of the array text file to read.
   

Returns:

    A multi-dimensional array built from the contents of <þcArrayFileþ>.
   

Description:

    DC_ARRAY_R() is used to create a multi-dimensional array
    from the contents of an array text file.  Only elements of the
    type L (logical), N (numeric), C (character), D (date), A
    (array) can be saved and restored.
   

Examples:

    PROCEDURE XTest()
   
    LOCAL aDir1, aDir2, cScrn
   
    DC_Gui(.t.)
   
    cScrn := DC_WaitOn()
    aDir1 := directory()
    dc_array_w( aDir1, "DIR.AR" )
    aDir2 := DC_ARRAY_R( "DIR.AR" )
    DC_Impl(cScrn)
   
    DC_Achoice( 5,10,20,30, DC_AConvert( aDir2 )[1] )
   
    RETURN
   

Source/Library:

  _DCARRAY.PRG/.OBJ, DCLIPX.LIB

See Also:

   RESTORE ARRAY
   dc_array_w()

dc_array_w()

Write contents of a multi-dimensional array to file

Syntax:

   DC_Array_Write ( < aArray >, ;
                    < cArrayFile > ) - > lStatus
   

Arguments:

   < aArray > is the name of the multi-dimensional array to save.
   
   < cArrayFile > is the name of the array text file to write.
   

Returns:

    .TRUE. if the array file was created, .FALSE. otherwise.
   

Description:

    DC_ARRAY_W() is used to save a multi-dimensional array to
    an array text file for later restoring with the DC_ARRAY_R()
    function for RESTORE ARRAY command.  Only elements of the type
    L (logical), N (numeric), C (character), D (date), A (array)
    can be saved and restored.
   

Examples:

    PROCEDURE XTest()
   
    LOCAL aDir1, aDir2, cScrn
   
    DC_Gui(.t.)
   
    cScrn := DC_WaitOn()
    aDir1 := directory()
    DC_ARRAY_W( aDir1, "DIR.AR" )
    aDir2 := dc_array_r( "DIR.AR" )
    DC_Impl(cScrn)
   
    DC_Achoice( 5,10,20,30, DC_AConvert( aDir2 )[1] )
   
    RETURN
   

Source/Library:

  _DCARRAY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_array_r()

dc_array2prg()

Save the contents of a multidimensional array to source code

Syntax:

    DC_Array2Prg ( < aArray >, ;
                   < cFileName >, ;
                  [< cFunction >], ;
                  [< cComments >], ;
                  [< cCode >] ) - > lStatus
   

Arguments:

   < aArray > is the name of the array to write.
   
   < cFileName > is the name of the file to create.
   
   < cFunction > is the name of the function to call that will
   return the array contents.  If this parameter is not passed
   then the function will be given the same name as the file.
   
   < cComments > is any comment heading to place at the top of
   the file.
   
   < cCode > is any source code that should be executed at the
   beginning of the function before returning the array
   contents.
   

Returns:

    A logical .t. if the file was created.
   

Description:

    DC_ARRAY2PRG() is used to create a .PRG file from the contents
    of a multi-dimensional array.   This allows the programmer
    to capture the contents of any array to a source code file
    that can be compiled and run to rebuild the array.
   

Notes:

    If the file being created already exists, then the user
    will be prompted to Append, Overwrite or Abort the
    operation.
   

Examples:

    -- Example 1 --
   
    . aMyArray := directory()
    . DC_ARRAY2PRG( aMyArray, "MYDIR" )
    . clip mydir  // compile mydir.prg
    . obj mydir   // load mydir.obj
    . aNewArray := MYDIR()
   
   
    -- Example 2 --
   
    . use all like cust*
    . browse tile       // configure browse windows
    . DC_ARRAY2PRG( DCBROWSE, 'MYBROWSE' )
    . clip mybrowse     // compile mbrowse.prg
    . obj mybrowse      // load mybrowse.obj
    . release dcbrowse  // kill old browse array
    . dcbrowse := MYBROWSE()
   

Source/Library:

  _DCARRAY.PRG, DCLIP1.DLL

See Also:

   dc_asave()

dc_arrayview()

A Tree style array/object browser

Syntax:

   DC_ArrayView( < aArray > | < oObject >, ;
                [< lExpand >] ) - > nil
   

Arguments:

   < aArray > is any type of array.
   
   < oObject > is any type of object.
   
   < lExpand > if .TRUE. will expand the tree.  The default is .FALSE.
   

Returns:

    NIL.
   

Description:

    DC_ARRAYVIEW() is used to browse multidimensional arrays
    and/or objects using a Tree-View style browser.
   
    The array can be any type of array with any dimensions and may
    contain any type of data. When expanding the array tree, the
    user has the option of opening a new window to display the
    contents of the sub-tree.  When expanding an object, the user
    has the option of displaying the properties of the object
    using DC_InspectObject().
   

Examples:

    PROCEDURE XTest()
   
    LOCAL aDir
   
    aDir := directory()
    DC_ArrayView( aDir )
   
    RETURN
   

Source/Library:

  _DCARRAY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_inspectobject()

dc_asave()

Save a multidimensional array to a binary file

Syntax:

   DC_ASave ( < aArray >, ;
              < cFileName > ) - > lStatus
   

Arguments:

   < aArray > is any multidimenstional array.
   
   < cFileName > is the name of the binary file to create with
   the array contents.
   

Returns:

    A logical .TRUE. if the array file was created, .FALSE.
    otherwise.
   

Description:

    DC_ASAVE() will save the contents of any multi-dimensional
    array to a binary file for later restoring with DC_ARESTORE().
   
    If the array contains code blocks, the code blocks will be
    saved and restored provide that they contain persistent data.
    Any code block that contains non-persistent data will be
    saved as a NIL.
   
    If the array contains pointers to objects, they pointers will
    be saved as a NIL.
   

Examples:

    PROCEDURE XTest()
   
    LOCAL aDir1, aDir2
   
    DC_Gui(.t.)
   
    aDir1 := Directory()
    DC_ASAVE( aDir1, 'ADIR.ARX' )
    aDir2 := DC_Arestore( 'ADIR.ARX' )
   
    DC_Achoice( 5,10,20,30, DC_AConvert( aDir2 )[1] )
   
    RETURN
   

Source/Library:

  _DCASAVE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_arestore()
   SAVE ARRAY

dc_at_clear()

Clear all prompts added by DC_At_Prompt()

Syntax:

   DC_At_Clear() - > nil
   

Arguments:

    None
   

Returns:

    NIL
   

Description:

    DC_AT_CLEAR() is used to clear the array that holds the
    menu prompts created with DC_AT_PROMPT().  This array
    is automatically cleared after calling DC_MENU_TO() so
    it is not necessary to call this function unless you
    wish to simply display menu prompts and not call the
    DC_MENU_TO() function to get a user selection.
   

Examples:

    dc_at_prompt( 10, 10, "Open a File", "Use a new database" )
    DC_AT_CLEAR() // changed my mind
   

Source/Library:

  _DCMENU2.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_at_prompt()
   dc_menu_to()

dc_at_prompt()

A moused replacement for AT..PROMPT

Syntax:

   DC_At_Prompt( < nRow >, ;
                 < nCol >, ;
                 < cPrompt >, ;
                 [< cMessage >] ) - > nil
   

Arguments:

   < nRow > is the screen row to display the prompt.
   
   < nCol > is the screen column to display the prompt.
   
   < cPrompt > is the prompt to display on the screen.
   
   < cMessage > is an optional message to display at the coordinates
   defined by the SET MESSAGE environment variable or by the
   message coordinates passed to DC_MENU_TO().
   

Returns:

    NIL
   

Description:

    DC_AT_PROMPT() is used with DC_MENU_TO() to replace Clipper
    @..PROMPT / MENU TO commands with a "mouseable" menu prompt
    system. The prompts and menu will behave exactly like the
    Clipper MENU TO system except the left button of the mouse will
    high-light the selected prompt, and the right button performs
    the same function as the <þENTERþ> key.
   

Examples:

    // display prompts
    DC_AT_PROMPT( 10, 10, "Open a File", "Use a new database" )
    DC_AT_PROMPT( 12, 10, "Open an Index", "Use an Index file" )
    DC_AT_PROMPT( 14, 10, "Edit database", "Browse all records" )
   
    // get a user selection and display message at row 20, col 25
    nChoice := dc_menu_to( 1, 20, 25 )
   

Source/Library:

  _DCMENU2.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_at_clear()
   dc_menu_to()

dc_atnext()

Find the next occurrence of a string in another string

Syntax:

   DC_AtNext ( < cCharacter >, ;
               < cString >, ;
               < nOccurrence > ) - > nPosition
   

Arguments:

   < cCharacter > is the character or substring to search.
   
   < cString > is the string to search.
   
   < nOccurrence > is the occurrence of < cCharacter > in < cString > to
   find.
   

Returns:

    The numeric location of the <þnOccurenceþ> of <þcCharacterþ> in
    <þcStringþ>.  If not found then 0 is returned.
   

Description:

    DC_ATNEXT() is used to return the location of the nth occurence
    of a substring within a string.
   

Examples:

    PROCEDURE XTest()
   
    LOCAL cString
   
    DC_Gui(.t.)
   
    cString := 'this is a test'
   
    DC_MsgBox( { cString, ;
                 DC_ATNEXT( 'is', cString, 1 ), ;
                 DC_ATNEXT( 'is', cString, 2 ) } )
   
    RETURN
   

Source/Library:

  _DCATNXT.PRG/.OBJ, DCLIPX.LIB

dc_atoattr()

Convert a Clipper color string to a screen color attribute

Syntax:

   DC_AtoAttr ( < cColorString > ) - > nColor
   

Arguments:

   < cColorString > is a valid Clipper color string.
   

Returns:

    A character string.
   

Description:

    DC_ATOATTR() is used to convert a Clipper color string to
    a numeric screen attribute. Screen attributes are represented
    as a number from 0 to 255 for a total of 256 colors.  Clipper
    functions require that a color string be used for setting
    colors rather than a number.
   

Examples:

    PROCEDURE XTest()
   
    DC_Gui(.t.)
   
    DC_MsgBox( { DC_ATOATTR( 'R/GR' ), ;
                 DC_ATOATTR( 'N/N' ), ;
                 DC_ATOATTR( 'W+*/W' ) } )
   
    RETURN
   

Source/Library:

  _DCCOLOR.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_attrtoa()

dc_attrtoa()

Convert a screen color attribute to a color string

Syntax:

   DC_AttrtoA ( < nColor > ) - > cColorString
   

Arguments:

   < nColor > is a number from 0 to 256.
   

Returns:

    A character string.
   

Description:

    DC_ATTRTOA() is used to convert a screen attribute to a
    color string.  Screen attributes are represented as a
    number from 0 to 255 for a total of 256 colors.  Clipper
    functions require that a color string be used for setting
    colors rather than a number.
   

Examples:

    PROCEDURE XTest()
   
    DC_Gui(.t.)
   
    DC_MsgBox( { DC_ATOATTR( 'R/GR' ), ;
                 DC_ATOATTR( 'N/N' ), ;
                 DC_ATOATTR( 'W+*/W' ) } )
   
    RETURN
   

Source/Library:

  _DCCOLOR.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_atoattr()

dc_autoresize()

Resize all objects to fit on the resized parent

Syntax:

   DC_AutoReSize( < aOldSize >, ;
                  < aNewSize >, ;
                  < oParent >, ;
                  < aGetList >, ;
                  < lToolBars > ) - > nil
   

Arguments:

   < aOldSize > is a 2 element array containing the width and height
   in pixels of the dialog window before resize.
   
   < aNewSize > is a 2 element array containing the widht and height
   in pixels of the dialog window after resize.
   
   < oParent > is the parent object.
   
   < aGetList > is the GetList array that was passed to DC_ReadGui().
   
   < lToolBars > if .FALSE. will not resize DCTOOLBAR or XbpPushButton
   objects.  These objects, if using bitmaps can truncate the image
   when resized.  The position of the ToolBar or PushButton will
   change accordingly but the size will not change.  The default
   is .TRUE. (resize all toolbars and pushbuttons).
   

Returns:

    NIL.
   

Description:

   DC_AutoReSize() is used to automatically resize and reposition
   all child objects so they use the real estate of the parent in
   the same proportions as the child objects before the parent was
   resized.
   
   DC_AutoReSize() is designed to be placed in a code block that is
   attached to the :resize callback slot of the parent object.
   
   The complete childlist tree is resized.
   

Notes:

   DC_AutoReSize() will not resize or reposition anything on a
   dialog that was painted with a Gra*() function or a DCGRA*
   command.
   
   Due to a bug in Xbase++ 1.3 make sure to add o:hide() and o:show()
   to your resize code block or the screen may leave some undesirable
   side effects after resizing objects.
   

Examples:

   FUNCTION XTest()
   
   LOCAL GetList := {}, oDesc, oBrowse
   
   USE COLLECT VIA DBFNTX
   
   @ 12,0 DCSAY COLLECT->descrip SAYSIZE 50 ;
      SAYOBJECT oDesc COLOR GRA_CLR_BLUE FONT '12.Courier Bold'
   
   @ .5,.5 DCBROWSE oBrowse ALIAS 'COLLECT' SIZE 49,9 ;
         EVAL {|o|o:itemMarked := {||oDesc:setCaption(COLLECT->descrip)} } ;
         HEADLINES 2 DELIMITER CHR(13)+CHR(10)
   
   DCBROWSECOL FIELD COLLECT->descrip HEADER "Description"+CHR(13)+CHR(10)+"Line
   2" ;
      PARENT oBrowse WIDTH 50
   
   DCREAD GUI FIT ADDBUTTONS ;
      EVAL {|o| o:resize := ;
          {|a,b,o|DC_AUTORESIZE(a,b,o,GetList),o:hide(),o:show()} }
   
   RETURN nil
   

Source/Library:

  _DCFUNCT.PRG, DCLIPX.DLL

See Also:

   DCGETOPTIONS

dc_average()

Average numeric fields in selected database

Syntax:

    DC_Average() - > lStatus
   

Arguments:

    None.
   

Returns:

    A logical .TRUE. if the average was not aborted.
   

Description:

    DC_Average() is used to average numeric fields from the currently
    selected database based on a set of conditions.  As GUI dialog
    window is displayed for the user to select the conditions.
   

Examples:

    . USE COLLECT
    . DC_Average()
   

Source/Library:

  _DCSUM.PRG, DCLIP2.DLL

See Also:

   SUM

dc_batch()

Process a Batch file with Dot-Prompt commands

Syntax:

   dc_batch ( < cFileName >, ;
              [< c1 >], ;
              [< c2 >], ;
              [< c3 >], ;
              [< c4 >], ;
              [< c5 >] ) - > nil
   

Arguments:

   < cFileName > is the name of the batch file to run.  If the
   extension is not given then .DCB is assumed.
   
   < c1 > , < c2 >, < c3 >, < c4 >, < c5 > are optional parameters that are
   subsituted by  %1 - %5 respectively in the batch file commands.
   

Returns:

    Nil.
   

Description:

    DC_Batch() will execute all commands in a .DCB batch file in
    sequential order.   A batch file can include any commands which
    can be entered at the dot-prompt and executed by the eXPress++
    interpreter other than structural commands, like DO WHILE, DO CASE
    IF..ENDIF or FOR..NEXT.  All commands in DCSTD.CH, DCDIALOG.CH,
    or DCCUSTOM.CH may be used in batch files.DC_BATCH() is used to open and
   execute a .DCB batch file. A
    "batch" file can contain any commands that can be interpreted
    at the dot prompt, including commands in .CH    files which
    have been loaded with the INCLUDE command or DC_PREINCLUDE()
    function.
   

Notes:

    DC_Dot() will automatically execute an AUTOEXEC.DCB batch file
    found in the directory containing the executable program or
    the or the directory named by the dos SET DCLIP=<þdirectoryþ>
    environment setting.
   

Examples:

    DC_BATCH('test.dcb')    // run TEST.DCB file
   

Source/Library:

  _dcbatch.prg, DCLIP1.DLL

See Also:

   BATCH
   INTERPRET
   dc_batchnewthread()

dc_batchnewthread()

Process a Batch file in a new thread

Syntax:

   DC_BatchNewThread ( < cFileName >, ;
                       [< c1 >], ;
                       [< c2 >], ;
                       [< c3 >], ;
                       [< c4 >], ;
                       [< c5 >] ) - > nil
   

Arguments:

   < cFileName > is the name of the batch file to run.  If the
   extension is not given then .DCB is assumed.
   
   < c1 > , < c2 >, < c3 >, < c4 >, < c5 > are optional parameters that are
   subsituted by  %1 - %5 respectively in the batch file commands.
   

Returns:

    Nil.
   

Description:

    DC_BatchNewThread() functions identically to DC_Batch() except
    it will execute in a new thread.
   

Notes:

    DC_Dot() will automatically execute an AUTOEXEC.DCB batch file
    found in the directory containing the executable program or
    the or the directory named by the dos SET DCLIP=<þdirectoryþ>
    environment setting.
   

Examples:

   . DC_BatchNewThread('test.dcb')    // run TEST.DCB file
   

Source/Library:

  _dcbatch.prg, DCLIP1.DLL

See Also:

   BATCH
   INTERPRET
   dc_batch()

dc_bin2num()

Converts a Binary String to a Number

Syntax:

   DC_Bin2Num( < cBinary > ) - > nDecimal
   

Arguments:

   < cBinary > is a string of up to eight 1's and 0's.
   

Returns:

    A numeric value from 0 - 255
   

Description:

   DC_BIN2NUM() will convert a binary string to a numeric value.
   

Source/Library:

  _DCAND.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_bittest()
   dc_xorbits()

dc_bitmapdraw()

Redraw a Bitmap Object on a GUI dialog screen

Syntax:

   DC_BitMapDraw ( < oParent >, ;
                   < ncbResource > ) - > nil
   

Arguments:

   < oParent > is the Static object that contains the presentation
   space for the bitmap.
   
   < ncbResource > is either the number of a resource that has been
   linked to the .EXE, a character string with the name of a
   *.BMP file, or a code block which, when evaluated, returns
   a number or character string.
   

Returns:

    Nil.
   

Description:

    DC_BITMAPDRAW() is used to redraw a Bitmap object that was created
    with the DCBITMAP command and painted on a dialog screen with
    DC_READGUI().
   
    This function is used to load a new *.BMP file into the
    presentation space previously created from the DCBITMAP object
    in the GetList.
   

Examples:

    #include 'dcdialog.ch'
   
    PROCEDURE XTest()
   
    LOCAL GetList := {}, cBitMap1, cBitMap2, oPhoto1, oPhoto2
   
    USE COLLECT NEW SHARED
    SKIP 2
   
    cBitMap1 := COLLECT->bitmap1
    cBitMap2 := COLLECT->bitmap2
   
    @  2,2 DCSTATIC XBPSTATIC_TYPE_RAISEDBOX SIZE 33,10 ;
       OBJECT oPhoto1
   
    @  2,37 DCSTATIC XBPSTATIC_TYPE_RAISEDBOX SIZE 33,10 ;
       OBJECT oPhoto2
   
    DCBITMAP cBitMap1 PARENT oPhoto1 AUTOSCALE
   
    DCBITMAP cBitMap2 PARENT oPhoto2 AUTOSCALE
   
    @  1,3  DCSAY 'Photo 1' GET cBitMap1 ;
       SAYRIGHT SAYSIZE 10 ;
       DATALINK {||DC_BitMapDraw(oPhoto1,cBitMap1)}
   
    @  1,38 DCSAY 'Photo 2' GET cBitMap2 ;
       SAYRIGHT SAYSIZE 10 ;
       DATALINK {||DC_BitMapDraw(oPhoto2,cBitMap2)}
   
    DCREAD GUI ;
       FIT ;
       ADDBUTTONS
   
    RETURN
   

Source/Library:

  _DCFUNCT.PRG/.OBJ, DCLIPX.LIB

See Also:

   DCBITMAP
   dc_readgui()
   DIALOG GETLIST

dc_bitmaptransparentcolor()

Set RGB transparent color for pushbutton bitmaps

Syntax:

   DC_BitmapTransparentColor( [< anColor >] ) - > nOldColor
   

Arguments:

   < anColor > is a 3-element array containing numeric RGB values or
   an numeric equivalent of an RGB color.
   

Returns:

   A numeric value.
   

Description:

   DC_BitmapTransparentColor() is a Get-Set function that is used
   to set the RGB value of the transparent color used with Bitmaps
   that are placed on DCPUSHBUTTON objects.
   

Examples:

   // set the transparent color to medium gray (the background
   // color of the bitmaps)
   
   aColor := { 192, 192, 192 }
   DC_BitmapTransparentColor( aColor )
   
   @ 0,0 DCPUSHBUTTON CAPTION DCBITMAP_FIND_1 SIZE 10,2
   DCREAD GUI FIT
   

Source/Library:

  _DCGETBX.PRG, DCLIPX.DLL

See Also:

   @ DCPUSHBUTTON
   dc_getbitmap()

dc_bittest()

Tests if a bit is set to 1 or 0 in a number

Syntax:

   DC_BitTest( < nDecimal >, ;
               < nBit > ) - > lStatus
   

Arguments:

   < nDecimal > is a numeric value from 0 to 255.
   
   < nBit > is the bit to test.  This is a value from 1 to 8.
   

Returns:

    A logical .TRUE. if the bit is a 1 and a logical .FALSE. if
    the bit is a 0.
   

Description:

   DC_BITTEST() will test for a specified bit in a number.
   

Source/Library:

  _DCAND.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_andbits()

dc_blank()

Blank all fields in the current record

Syntax:

    DC_Blank( [< lCommit >] ) - > lStatus
   

Arguments:

   < lCommit > if .TRUE. (default) will commit the changes to disk.
   

Returns:

    A logical .TRUE. if the record was blanked.
   

Description:

    DC_BLANK() is used to blank the contents of all fields in the
    current record of the current work area.  It is not necessary
    to lock the record because DC_BLANK() will also lock and unlock
    the record before blanking the contents.
   

Examples:

    . USE COLLECT
    . GO 5
    . DC_Blank()
   

Source/Library:

  _dcblank.prg, DCLIP1.DLL

See Also:

   BLANK
   dc_isblank()

dc_bof()

Is the record pointer at the beginning of the file?

Syntax:

    DC_Bof() - > lStatus
   

Arguments:

    None.
   

Returns:

    A logical value.
   

Description:

    DC_BOF() is used to test whether or not DC_DbSkip() attempted
    to move the record pointer past the top record in a "scoped"
    set of records when using a negative skip value.  If no scope
    is set or the ADSDBE is being used as the data driver for the
    current work area this function simply calls Bof() therefore
    it can be used as a replacement for Bof().
   

Notes:

Examples:

    DC_SetScope(0,'12001')
    DC_SetScope(1,'12001')
   
    DC_DbGoBottom()
   
    DO WHILE !DC_Bof()
      DC_DbSkip(-1)
    ENDDO
   

Source/Library:

  _DCSCOPE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_setscope()
   dc_eof()
   dc_dbskip()
   dc_dbgotop()
   dc_dbgobottom()

dc_browcelledit()

Edit Cells of a Browse Object

Syntax:

   DC_BrowCellEdit( < oBrowse >, ;
                    [< nRow >],  ;
                    [< nCol >],  ;
                    [< nEditMode >],  ;
                    [< lArray >],  ;
                    [< abDefault >],  ;
                    [< bEval >]  ) - > nil
   

Arguments:

   < oBrowse > is the browse object to edit, insert or delete.  This
   must be an object of the XbpBrowse class.
   
   < nRow > is the starting row.  If this argument is not passed,
   then the currently selected row is the default.  < nRow > must
   be a numeric value within the currently visible number of rows.
   
   < nCol > is the starting column.  If this argument is not passed,
   then the currently selected column is the default.  < nCol > must
   be a numeric value between 1 and the total number of columns in
   the browse object.
   
   < nEditMode > is the editing and/or navigation mode.
   
    < nEditMode >             Description
    -----------             ---------------------------------------
    DCGUI_BROWSE_EDITEXIT   Edit - Exit cell editing after ENTER key
    DCGUI_BROWSE_EDITACROSS Edit - Move to next column after ENTER key
    DCGUI_BROWSE_EDITDOWN   Edit - Move to next row after ENTER key
    DCGUI_BROWSE_INSERT     Insert an element or a record
    DCGUI_BROWSE_DELETE     Delete current element or record
   
   < lArray > is a logical value determining if the browsed data is an
   array or a database.  If .TRUE., then it is an array.  If this
   argument is not passed and the browse object was created via the
   DCBROWSE command then this is determined automatically.  If an
   array is being browsed, then the :cargo iVar of the browse object
   must contain an array of at least 5 elements.  Element 5 is a
   pointer to the array being browsed.  Element 4 is a numeric
   value containing a pointer to the currently selected array
   element.
   
   < abDefault > is used only when inserting an array element, ie
   < nMode > is DCGUI_BROWSE_INSERT.  This parameter contains either
   an array or a code block which returns an array.  The array
   contains the default data for the inserted element.  Note: array
   browsers always browse multi-dimensional, symmetrical arrays, so
   this array must contain the same number of sub-elements as each
   array element.
   
   < bEval > is an optional code block to evaluate before inserting,
   deleting, or editing a cell row.
   

Description:

    DC_BrowCellEdit() is used to edit the cells of any browse object.
    Navigation modes allow for moving up and down within the browse
    via the UP, DOWN keys or automatically moving DOWN or ACROSS
    with the ENTER key.
   
    DC_BrowCellEdit() supports WHEN code blocks for each column to
    prevent the editing of a cell and VALID code blocks for each
    column to validate user input.
   
    DC_BrowCellEdit() also is used to delete an element from the
    array being browsed or to insert and edit a new element.
   

Notes:

    The :dataLink iVar of each XbpColumn object in the XbpBrowse
    object is used to store the GET/SET code block for editing the
    cell.  If the XbpColumn objects were created by the DCBROWSECOL
    command using the FIELD <þcFieldþ> clause, then it will automatically
    be created as a GET/SET code block.
   
    The :cargo iVar of each XbpColumn object in the XbpBrowse object
    may be used to store WHEN clause and VALID clause information.
    If the column objects were created by the DCBROWSECOL command