Documentation for Win32lib v0.70.18
Table of Contents

Miscellaneous

Routines that don't easily fit into other categories.


  • proc Beep(atom style)   Sounds one of the standard beeps.
  • func FormatMsg(object pTextCode, sequence pData)    Fetches the format template associated with pTextCode and applies pData to it.
  • func getOpt(sequence pSource, sequence pCategory, sequence pKey, object pDefault)    Retrieves the data associated with pKey in the file pSource under the group pCategory
  • func getRandInt(atom pMin, atom pMax)   Gets a random number.
  • func makeStandardName(sequence Name)   Transforms a string into a standardized format suitable for naming things.
  • func setContainer(object pNew)    Defines the message file that is used by Usetext
  • func setUserLanguage(object pNew)    Defines or returns the language category that is used by UseText
  • func UseText(object pTextCode, sequence pDefault)    Fetches the text associated with pTextCode
  • func w32MaxWidth(object pData)    Computes the maximum width of elements of pData.
  • func w32MinSequenceSize(sequence pList, integer pMinSize, object pNewData)    Pads pList to the right until its length reaches pMinSize using pNewData as filler.
  • func w32rand32(atom N)   
  • func w32ToString(object pData)    Assembles a sequence from the substrings in pData, separated by commas.

    Documentation for Win32lib v0.70.18
    Table of Contents

    [proc]
    Beep
    (atom style)

    Sounds one of the standard beeps.

    Category: Miscellaneous

    style can be one of ...

  • -1 Standard beep using the computer speaker
  • MB_ICONASTERISK SystemAsterisk
  • MB_ICONEXCLAMATION SystemExclamation
  • MB_ICONHAND SystemHand
  • MB_ICONQUESTION SystemQuestion
  • MB_OK

    Example

      Beep( MB_ICONEXCLAMATION )
    

    See Also: FormatMsg, getOpt, getRandInt, makeStandardName, setContainer, setUserLanguage, UseText, w32MaxWidth, w32MinSequenceSize, w32rand32, w32ToString


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    FormatMsg
    (object pTextCode, sequence pData)

    Fetches the format template associated with pTextCode and applies pData to it.

    Returns: SEQUENCE: The formatted text.

    Category: Miscellaneous

    This searches the current messages file (see setContainer ) for the text code in the current language category (see setUserLanguage ) and when found the function uses it as a template with formatting codes in it.

    pTextCode is either the code (an integer) to search for templates in the messages file, or a message template itself.
    pData is either a single string or a sequence of strings.

    A message template can contain zero or more place-holder tokens. Each token is replaced by its respective value from the pData to form the final output. A token is either a two-character one in the form of '%N' where 'N' is a digit from 1 to 9, or a token in the form '%{X}' where 'X'

    Example:
    Assume you have the following messages file ...

    [english]
    1 = File '%{NAME}' not found in folder '%{PATH}'
    2 = Record ID '%1' not found
    3 = Record ID '%1' already exists
    9 = Internal error: Code '%1'.
    5001 = Unknown error code: '%1'
    

    Then we can call this function thus ...

          sequence lText
          lText = FormatMsg(1, {"PATH=c:\\temp\\", "NAME=link.opt"} ) -- returns "File 'link.opt' not found in folder 'c:\temp\'"
          lText = FormatMsg(3, "djp") -- returns "Record ID 'djp' already exists"
          lText = FormatMsg(17, "Some Text") -- returns "Unknown error code: Msg#17, Some Text"
          lText = FormatMsg("%1 %3, %2", {"Mr", "Derek", "Parnell"}) -- returns "Mr Parnell, Derek"
    

    See Also: Beep, getOpt, getRandInt, makeStandardName, setContainer, setUserLanguage, UseText, w32MaxWidth, w32MinSequenceSize, w32rand32, w32ToString


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    getOpt
    (sequence pSource, sequence pCategory, sequence pKey, object pDefault)

    Retrieves the data associated with pKey in the file pSource under the group pCategory

    Returns: OBJECT: The associtated data.

    Category: Miscellaneous

    pSource is the name of a text file in which the data can be found.
    pCategory is the name of a category, or grouping, found in pSource. The categories are coded in the file in the form ("[" category "]") as the only thing in a line.
    pKey is the key that will be searched for in the category. If found the associated string will be returned otherwise pDefault is returned.
    pDefault is a string to be returned if the key is not found in the file.

    Note that the category and key are not case sensitive.

    Any text that begins with "->" is ignored to the end of line. This is how you add comments to the source file.

    If the associated data can be converted to a Euphoria atom it will be, otherwise it will be returned as a text string. With the exception that the strings "yes", "true", "on" will be returned as the integer 1 (one), and the strings "no", "false", "off" will be returned as the integer 0 (zero). If you actually need any of these strings to be returned verbatim then enclose them in quotes in the file.

    If the associated text contains "\n" or "\t" these are replaced with 10 (newline) and 9 (tab) respectively.

    The associated data can span multiple lines. This done by simply having the continuation lines begin in column 2 or greater.

    Example:
    Assume we have an options file, App.Ini, containing the following lines ...

    [COMMS]
    Baud=9600
    Stop=1
    Bits=7
    Parity=Odd
    AutoConnect=yes
    ACKResponse="yes"
    Welcome= "Application V1.0\n"
             "Welcome to my application.\n"
             "(c) 2004 HardMacro"
    

    [COLOR] Background = White Text = Black Highlight = Blue Selection = Pink

    [LIMITS] Files = 10 DBSize = 1024 -> MB

    then we could call this routine ...

          object lRes
          lRes = getOpt("App.Ini", "color", "text", "Gray") -- Returns "Black"
          lRes = getOpt("App.Ini", "comms", "autoconnect", "no") -- Returns 1
          lRes = getOpt("App.Ini", "comms", "ACKResponse", "none") -- Returns "yes"
          lRes = getOpt("App.Ini", "comms", "Parity", "even") -- Returns "Odd"
          lRes = getOpt("App.Ini", "comms", "CRC", "yes") -- Returns "yes"
          lRes = getOpt("App.Ini", "User", "ID", -1) -- Returns -1
          lRes = getOpt("App.Ini", "limits", "files", -1) -- Returns 10
          lRes = getOpt("App.Ini", "limits", "connections", 4) -- Returns 4
          lRes = getOpt("App.Ini", "limits", "DBSize", 16) -- Returns 1024
          lRes = getOpt("App.Ini", "comms", "welcome", "") -- Returns ...
    Application V1.0
    Welcome to my application.
    (c) 2004 HardMacro
    

    See Also: Beep, FormatMsg, getRandInt, makeStandardName, setContainer, setUserLanguage, UseText, w32MaxWidth, w32MinSequenceSize, w32rand32, w32ToString


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    getRandInt
    (atom pMin, atom pMax)

    Gets a random number.

    Returns: ATOM: A random number from Min and Max inclusive.

    Category: Miscellaneous

    This uses the cryptographic routines built into Windows. It gathers entropy from various sources in between calls and thus you cannot seed this generator to produce a known stream of numbers.

    pMin and pMax are limited to 32-bit integer values.

    Example:

          integer guess
          Get a random number between 4 and 19.
          guess = getRandInt(4, 19)
    

    See Also: Beep, FormatMsg, getOpt, makeStandardName, setContainer, setUserLanguage, UseText, w32MaxWidth, w32MinSequenceSize, w32rand32, w32ToString


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    makeStandardName
    (sequence Name)

    Transforms a string into a standardized format suitable for naming things.

    Returns: SEQUENCE: A Standard Name format

    Category: Miscellaneous

    Name is any string. It is converted to a standard form by removing any characters that are not alphanumeric, except that the first character can only be alphabetic or the underscore character.

    Example:

          sequence lName
          lName = makeStandardName("Customer Dialog #1")
          -- This should return "CustomerDialog1"
    

    See Also: Beep, FormatMsg, getOpt, getRandInt, setContainer, setUserLanguage, UseText, w32MaxWidth, w32MinSequenceSize, w32rand32, w32ToString


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    setContainer
    (object pNew)

    Defines the message file that is used by Usetext

    Returns: SEQUENCE: The previous setting.

    Category: Miscellaneous

    Initially the file name is set to "msgs.ini". You would use this if the messages file containing the text has a different name or is on a different path.

    If pNew is a sequence, it is the name and path of the file that will be searched by UseText. Otherwise, the current file name and path will be returned.

    Example:

      -- Get current value
      sequence lCurrent
      lCurrent = setContainer( 0 ) -- Any non-sequence parameter value will do.
    

    sequence lOld lOld = setContainer( "Application\\Data\\Message.Text" )

    See Also: Beep, FormatMsg, getOpt, getRandInt, makeStandardName, setUserLanguage, UseText, w32MaxWidth, w32MinSequenceSize, w32rand32, w32ToString


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    setUserLanguage
    (object pNew)

    Defines or returns the language category that is used by UseText

    Returns: SEQUENCE: The previous setting.

    Category: Miscellaneous

    Initially the language is set to "english". You would use this if the messages file contained other language catgories.

    If pNew is a sequence, it is the category that will be searched by UseText in the messages file. Otherwise, the current language string will be returned.

    Example:

      -- Get current setting
      sequence lCurrent
      lCurrent = setUserLanguage( 0 ) -- Any non-sequence parameter value will do.
    

    sequence lOld lOld = setUserLanguage( "thai" ) -- Note that the category can be anything. lOld = setUserLanguage( "geek jargon" )

    See Also: Beep, FormatMsg, getOpt, getRandInt, makeStandardName, setContainer, UseText, w32MaxWidth, w32MinSequenceSize, w32rand32, w32ToString


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    UseText
    (object pTextCode, sequence pDefault)

    Fetches the text associated with pTextCode

    Returns: SEQUENCE: The text.

    Category: Miscellaneous

    This searches the current messages file (see setContainer ) for the text code in the current language category (see setUserLanguage ) and when found returns the associated text string.

    If no associated text could be found and no default was supplied, it returns the value of pTextCode enclosed with MSG[ and ].

    Example:
    Assume you have the following messages file ...

    [english]
    0 = Okay
    1 = File not found
    2 = Record not found
    3 = Record already exists
    9 = Internal error.
    UM = Unit of Measure
    KG = Kilogram
    

    Then we can call this function thus ...

          sequence lText
          lText = UseText(0, "") -- returns "Okay"
          lText = UseText(9, "") -- returns "Internal error."
          lText = UseText("KG", "kilo") -- returns "Kilogram"
          lText = UseText("KM", "") -- returns "MSG[KM]"
    

    See Also: Beep, FormatMsg, getOpt, getRandInt, makeStandardName, setContainer, setUserLanguage, w32MaxWidth, w32MinSequenceSize, w32rand32, w32ToString


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32MaxWidth
    (object pData)

    Computes the maximum width of elements of pData.

    Returns: The maximum width.

    Category: Miscellaneous

    The width of a string is its length. The width of an atom is the length of its string representation using the %15.15g format specifier.

    See Also: Beep, FormatMsg, getOpt, getRandInt, makeStandardName, setContainer, setUserLanguage, UseText, w32MinSequenceSize, w32rand32, w32ToString


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32MinSequenceSize
    (sequence pList, integer pMinSize, object pNewData)

    Pads pList to the right until its length reaches pMinSize using pNewData as filler.

    Returns: The padded sequence, unchanged if its size was not less than pMinSize on input.

    Category: Miscellaneous

    See Also: Beep, FormatMsg, getOpt, getRandInt, makeStandardName, setContainer, setUserLanguage, UseText, w32MaxWidth, w32rand32, w32ToString


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32rand32
    (atom N)

    Returns: A random integer between 1 and N. N may be any atom representing a 32-bit integer.

    Category: Miscellaneous

    See Also: Beep, FormatMsg, getOpt, getRandInt, makeStandardName, setContainer, setUserLanguage, UseText, w32MaxWidth, w32MinSequenceSize, w32ToString


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32ToString
    (object pData)

    Assembles a sequence from the substrings in pData, separated by commas.

    Returns: A sequence concatenating all substrings of pdata, with a comma as separator.

    Category: Miscellaneous

    The returned sequence is enclosed between '(' and ')'.

    See Also: Beep, FormatMsg, getOpt, getRandInt, makeStandardName, setContainer, setUserLanguage, UseText, w32MaxWidth, w32MinSequenceSize, w32rand32