Announcement

Collapse
No announcement yet.

PB/Win 10 & PB/CC 6 -- What's new?

Collapse
This topic is closed.
X
X
  • Filter
  • Time
  • Show
Clear All
new posts

  • PB/Win 10 & PB/CC 6 -- What's new?

    Static Link Libraries
    =====================

    What is an SLL?
    ---------------
    An SLL is a Static Link Library. It consists of a set of Classes,
    Subs, and Functions which are compiled into a machine-code library.
    Since it is a library, the code cannot be executed standalone. It
    functions much like a DLL would, but the pre-compiled machine code
    is actually embedded into the final .EXE or .DLL to reduce the
    number of files in your project.


    Why use SLLs?
    -------------
    A Static Link Library is the perfect vehicle for third-party code,
    because it creates a single final module while not requiring source
    code to be distributed. It allows you to create a group of your own
    libraries, which you know function correctly and don't require any
    further debugging. It also offers big advantages to larger group
    programming projects to control distribution of various elements.


    Creating a Static Link Library
    ------------------------------
    Creation of an SLL couldn't be easier. All it takes is a single
    metastatement at the top of your module source code:

    #COMPILE SLL

    If your source code file is named "ABC.BAS", then your Static Link
    Library will automatically be named "ABC.SLL". (You can check the
    #COMPILE section for additional naming options.) When you wish to
    use the SLL code in a host program, you use:

    #LINK "ABC.SLL"

    and the contents are automatically embedded in the new .EXE or .DLL.
    It's just that simple.


    Common Subs and Functions
    -------------------------
    A COMMON Sub or Function is one which is visible between the primary
    host program and one or more SLL unit modules. A Sub/Function is
    defined as COMMON by inserting that word as one of the descriptors:

    FUNCTION MyFunc(Parm AS LONG) COMMON AS DOUBLE
    <Function code>...
    END FUNCTION

    If you wish to reference a Sub/Function which is located in an
    external module (another SLL or the Host module), you must likewise
    include the word COMMON as a descriptor in the DECLARE statement:

    DECLARE FUNCTION MyFunc(Parm AS LONG) COMMON AS DOUBLE

    Of course, when the host module is compiled, all references to
    COMMON items must be resolved accurately, or an appropriate error
    will be generated. Any Sub/Function not defined as COMMON may not
    be shared between modules.

    The EXPORT descriptor identifies a Sub/Function which may be accessed
    between Dynamic Link Libraries (DLLs), and/or the main executable
    which links them. If a procedure is not marked EXPORT, it is hidden
    from these other modules. Generally speaking, it's best not to mark
    a Sub/Function in an SLL as EXPORT. While it is syntactically
    acceptable, it may limit your future options when linking the SLL
    into host modules. PowerBASIC recommends that you mark them as
    COMMON in the SLL, and add the EXPORT attribute in the host module.

    It's easy to create an SLL which can be linked into an executable
    program or a dedicated DLL for the same purpose. To add the EXPORT
    attribute to a linked Sub/Function, just add the word EXPORT to the
    DECLARE statement in the host module or add an $EXPORT metastatement.

    #EXPORT MyFunc
    DECLARE FUNCTION MyFunc(Parm AS LONG) COMMON EXPORT AS DOUBLE

    Using this technique, your SLL can be linked directly into an
    application executable without publishing the Subs/Functions as
    EXPORT. However, you can also link the same SLL into a DLL host
    module which adds the EXPORT attribute to any or all of the COMMON
    Subs and Functions in the corresponding DECLARE statements.

    For example, let's say you want to make a library which publishes
    the SUB named XXX. You want to provide it in two forms, a linkable
    SLL and an industry standard DLL. So, first just create the SLL:

    #COMPILE SLL = "XXXLib.SLL"

    SUB xxx() COMMON
    MSGBOX "Hello"
    END SUB

    Just compile it, and you're ready to link it into your application.
    But now you want to create a DLL, too, since it might be used with
    other applications. It's just this easy:

    #COMPILE DLL = "XXXLib.DLL"

    #EXPORT xxx
    #LINK "XXXLib.SLL"

    That's all there is to it. You now have an SLL and an equivalent
    DLL to do the job of the XXX procedure.


    Common Classes and Objects
    --------------------------
    A COMMON Class is one which is visible between the primary host
    module and one or more SLL unit modules. A Class is defined as
    COMMON by inserting that word as a Class Descriptor:

    CLASS MyClass $MyGuid COMMON
    <Class code>...
    END CLASS

    A class which is declared AS COM makes it available to external
    programs through the COM services of Windows. You can define a
    class to be both COM and COMMON by adding both descriptors.
    However, a COM Class is automatically considered to be COMMON
    as well.

    CLASS MyClass $MyGuid COMMON AS COM
    <Class code>...
    END CLASS


    Unreferenced Code
    -----------------
    Any code in an SLL marked COMMON, COM, or EXPORT is always included
    in your compiled SLL module. Any additional code referenced by them
    is also included. All other unused code is automatically extracted
    at the time the SLL is compiled. Keep in mind that the resulting
    SLL module is pre-compiled, and cannot be modified further.

    When you link an SLL into a host module, it is examined carefully
    by the compiler. If it is determined that no code in the SLL is
    needed, the SLL is simply not linked. This can reduce the size of
    your final program substantially. However, if even one procedure
    in an SLL is used, the entire SLL is included. Therefore, it may
    be in your best interest to split up your code into multiple SLL
    modules. The PowerBASIC Compiler will pick and choose exactly
    which ones are needed and ignore the rest. This assures the
    smallest possible size of the resulting application.


    Managing Multiple SLL Modules
    -----------------------------
    For your convenience, multiple SLL modules may be collected into a
    Power Library, which is linked as a single item. However, the
    PowerBASIC Compiler treats the component modules individually, just
    as though they were each linked separately. A component SLL in a
    Power Library which is not needed is ignored entirely.

    SLL modules are collected into a Power Library with the PowerLib
    utility librarian. This GUI application can readily add, remove,
    replace, or list the component SLL modules. Optionally, you can
    also use a command line librarian if that better serves your needs.
    The default file extension for Power Libraries is ".PBLIB".

  • #2
    PB/Win 10 &amp; PB/CC 6 -- What's new?

    #OPTIMIZE metastatement

    Purpose
    Choose the optimization which should be applied to your program.

    Syntax
    #OPTIMIZE CODE [ON|OFF]
    #OPTIMIZE [SIZE | SPEED]

    Remarks
    The #OPTIMIZE metastatement is used to tell the compiler your
    preferences in regards to the optimization of generated code.

    The first form of the directive (CODE) tells the compiler whether
    unreferenced code should be removed from the compiled program to
    minimize the executable file size. This option defaults to ON as
    there are few reasons to disable it (other than curiosity as to
    the effectiveness). Regardless of the compiled module type (SLL,
    DLL, or EXE), PowerBASIC removes every unneeded:

    1- Sub
    2- Function
    3- FastProc
    4- Method
    5- Property
    6- String Literal
    7- Numeric Literal
    8- Static Link Library

    Extraction is always performed on a procedure basis, not an entire
    class. If you have a CLASS with 50 Methods, but only one is ever
    called, the other 49 are removed entirely. This level of granularity
    is particularly important with your personal code library of general
    purpose functions. You can include them all, and PowerBASIC will
    use just the minimum necessary. If you generate a log file (using
    the /L command line option), a list of the extracted procedures,
    classes, and SLL modules is provided.

    The second form of the directive (SIZE/SPEED) tells the compiler
    whether you want additional optimization for execution speed or
    smaller total code size. If not used, the default is to choose
    faster code speed.

    If you choose the SPEED option, one of the important actions of the
    compiler is to align heavily used code sections on an address
    boundary which is most beneficial to the CPU/FPU.

    In some cases, the speed of looping mechanisms (FOR/NEXT, DO/UNTIL...)
    can be improved by as much as 100%, and occasionally even more.

    Comment


    • #3
      PB/Win 10 &amp; PB/CC 6 -- What's new?

      #RESOURCE metastatement

      Purpose
      Embed PowerBASIC Resource Data into a compiled EXE or DLL.

      Syntax
      #RESOURCE BITMAP, ResID, "filespec.BMP"
      #RESOURCE ICON, ResID, "filespec.ICO"
      #RESOURCE MANIFEST, 1, "filespec.XML"
      #RESOURCE RCDATA, ResID, "filespec.DAT"
      #RESOURCE STRING, ResID, "YourWideText"$$ [,LangID]
      #RESOURCE TYPELIB, 1, "filespec.TLB"
      #RESOURCE VERSIONINFO <<block>>

      #RESOURCE RES, "filespec.RES"
      #RESOURCE PBR, "filespec.PBR"

      Remarks
      This metastatement is used to include PowerBASIC Resource data into
      your program or DLL. Resource data may consist of Bitmaps, Icons,
      Strings, COM Type Libraries, Version Information, and more. You can
      even embed custom binary data for your personal, specialized needs.

      Resource data can be a very valuable tool. While you can certainly
      load bitmaps and icons from separate files, wouldn't it be better to
      just embed them in your application? When you need the bitmap, it's
      always right there for your use! You don't have to deal with scads
      of files. Now it's all at your fingertips.

      The parameter ResID is a unique identifier which you create to
      reference this item. It can be a number or an alphanumeric label.
      If a number, it must be an integral value from 1 to 32767. If a
      label, it must begin with a letter, and consist of letters and
      numbers. Alphanumeric labels are not case sensitive. The filespec
      parameter must always be expressed as a string literal which tells
      the location of the resource data.

      With most programming languages, creation and embedding of resource
      data is a cumbersome process. First you create a resource script
      (an .RC file) with a text editor. Then you save the .RC file. Now,
      compile the .RC file with a resource compiler to get a .RES file.
      Next, you convert it to a linkable file using Microsoft's CVTRES.EXE
      or another converter program like PBRES.EXE. Finally, you link it
      into your .EXE or .DLL with a compiler or linker program. What if
      you find you need to make a tiny change? Do it all over again, from
      the beginning. Even older versions of PowerBASIC suffered from this
      problem.

      Isn't there a better way? Yes, PowerBASIC now handles the entire
      process in a single line of code. Need an an embedded bitmap?

      #RESOURCE BITMAP, 123, "MyPicture.BMP"

      PowerBASIC finds your bitmap in the file MyPicture.BMP and embeds
      it in your executable. When you need to use it, you can reference
      it by the ID you chose for it (123). The ID can be an integral
      numeric value or a text name of your choice. So, to display the
      bitmap on a graphic window, it's as simple as:

      GRAPHIC RENDER "#123", (100,100)-(160,140)


      String Resources
      ================
      The String resource contains string data which is always created
      and stored as Wide Unicode characters. It is retrieved at run-time
      with the RESOURCE$ function. Due to the manner in which Windows
      stores string resources in a string table, the ResID must be numeric.

      The string data must be from 1 to 127 characters in length, and may
      not contain any embedded nuls (CHR$(0)). The string data may be
      specified as a quoted wide string literal ("MyText"$$), or as a
      wide string literal expression. A string literal expression can be
      constructed from combinations of wide string equates or wide quoted
      string literals, the CHR$ function, SPACE$ function, and the STRING$
      function when used with numeric parameters.


      VersionInfo Resources
      =====================
      The VersionInfo resource contains information about the file, such
      as its version number, its intended operating system, its original
      file name, and much more. This resource is intended to be used with
      the Version Information API functions, so that Windows Explorer, and
      other programs, can display the relevant information about your EXE
      or DLL. The VERSIONINFO resource cannot be embedded in a Static
      Link Library (SLL).

      The VersionInfo resource is unique in that it requires several
      #RESOURCE metastatements which are interpreted as a complete block.
      They must be placed consecutively in the correct sequence in order
      be processed correctly.

      1- The block begins with the VersionInfo metastatement which
      marks the beginning of the version block.

      #RESOURCE VersionInfo

      2- Next, you may choose to add one or more of the numeric
      version metastatements which embed numeric values.

      #RESOURCE FileFlags FlagValue&
      #RESOURCE FileVersion HiNum1&, LoNum1&, HiNum2&, LoNum2&
      #RESOURCE ProductVersion HiNum1&, LoNum1&, HiNum2&, LoNum2&

      3- Next, the mandatory StringInfo metastatement is added, to
      identify the Language ID and CharSet to be used. Each of these
      parameters must be passed as a 4-digit HEX value in a string
      literal. The parameter must not contain the "&H" prefix used
      with numeric hex numbers.

      #RESOURCE StringInfo "LangID", "CharSet"

      4- Finally, you will add one or more of the string version
      metastatements, to provide extensive information about the file.
      The first string literal parameter chooses one of the following
      predefined names. The second string literal parameter adds your
      personal choice of information about the file.

      #RESOURCE Version$ "Comments", "Additional info"
      #RESOURCE Version$ "CompanyName", "PowerBASIC Inc."
      #RESOURCE Version$ "FileDescription", "Presented to users"
      #RESOURCE Version$ "FileVersion", "Readable VerNum 1.02"
      #RESOURCE Version$ "InternalName", "Private"
      #RESOURCE Version$ "LegalCopyright", "Copyright 2010 PB Inc"
      #RESOURCE Version$ "LegalTrademarks", "xx is a..."
      #RESOURCE Version$ "OriginalFilename", "Original name w/o path"
      #RESOURCE Version$ "PrivateBuild", "Private info"
      #RESOURCE Version$ "ProductName", "Product distributed with"
      #RESOURCE Version$ "ProductVersion", "Version distributed with"
      #RESOURCE Version$ "SpecialBuild", "Special info"

      FileFlags Flagvalue
      -------------------
      %VS_FF_DEBUG File contains debugging information or is compiled
      with debugging features enabled.

      %VS_FF_PATCHED File has been modified and is not identical to the
      original shipping file of the same version number.

      %VS_FF_PRERELEASE File is a development version, not a commercially
      released product.

      %VS_FF_PRIVATEBUILD File was not built using standard release
      procedures. If this value is given, you must
      include a PrivateBuild string item.

      %VS_FF_SPECIALBUILD File was built by the original company using
      standard release procedures, but is a variation of
      the standard file of the same version number. If
      this value is given, uou must include a
      SpecialBuild string item.

      LangID (HEX values)
      -------------------
      0401 Arabic 0415 Polish
      0402 Bulgarian 0416 Portuguese (Brazil)
      0403 Catalan 0417 Rhaeto-Romanic
      0404 Traditional Chinese 0418 Romanian
      0405 Czech 0419 Russian
      0406 Danish 041A Croato-Serbian (Latin)
      0407 German 041B Slovak
      0408 Greek 041C Albanian
      0409 U.S. English 041D Swedish
      040A Castilian Spanish 041E Thai
      040B Finnish 041F Turkish
      040C French 0420 Urdu
      040D Hebrew 0421 Bahasa
      040E Hungarian 0804 Simplified Chinese
      040F Icelandic 0807 Swiss German
      0410 Italian 0809 U.K. English
      0411 Japanese 080A Spanish (Mexico)
      0412 Korean 080C Belgian French
      0413 Dutch 0816 Portuguese (Portugal)
      0414 Norwegian - Bokmal 081A Serbo-Croatian (Cyrillic)
      0810 Swiss Italian 0C0C Canadian French
      0813 Belgian Dutch 100C Swiss French
      0814 Norwegian - Nynorsk

      CharSet (HEX values)
      --------------------
      0000 7-bit ASCII 04E3 Cyrillic
      03A4 Japan (Shift JIS X-0208) 04E4 Multilingual
      03B5 Korea (Shift KSC 5601) 04E5 Greek
      03B6 Taiwan (Big5) 04E6 Turkish
      04B0 Unicode 04E7 Hebrew
      04E2 Latin-2 (Eastern Europe) 04E8 Arabic


      RES/PBR Resources
      =================
      The second group of syntax examples show how you can embed resources
      which have been pre-compiled used a resource compiler. Standard
      resource compilers output a binary resource with a .RES extension.
      PowerBASIC will embed this resource just as it is given in the file.
      This form will always be supported to support resource forms
      which are typically not needed for most PowerBASIC programs,
      or which usually require the use of a resource editor.

      The final example, using a .PBR file, will only be supported for a
      limited period of time. This is the form created by the PowerBASIC
      PBRES utility in older versions of the compiler. It is recommended
      that you change to the .RES version soon, as it is more efficient,
      and needs less effort from the programmer. It should be noted that
      prior versions of PowerBASIC allowed the descriptor "PBR" to be
      omitted. While this option will be supported for a limited period
      of time, we recommend that you always insert "PBR" for clarity.

      Comment


      • #4
        PB/Win 10 &amp; PB/CC 6 -- What's new?

        ENUM...END ENUM statements

        Purpose
        Creates a group of logically related numeric equates.

        Syntax
        ENUM Name [SINGULAR] [BITS] [AS COM]
        EquateName [= value]
        EquateName [= value]...
        END ENUM

        Remarks
        PowerBASIC allows you to refer to integral numeric constants by name.
        These names are called equates, and are visible throughout your
        program. If you need a set of equates which are logically related,
        you can define them as a group in an enumeration. This provides
        meaningful names for the enumeration, its members, and therefore the
        name by which it is referenced.

        When an equate is created in an enumeration, its name is composed of
        a leading percent sign (%), the enumeration name, a period (.), and
        then the member name. For example:

        ENUM abc
        count = 7
        END ENUM

        In the above example, the equate is referenced as %abc.count, and
        returns the value seven (7).

        Each member of an enumeration may be assigned a specific integral
        value (in the range of a 64-bit quad integer) by using the optional
        [=value] syntax. In this case, only a constant value (or a simple
        constant/literal expression) may be assigned to it. If an expression
        is used, all of the terms in the expression must be constants; numeric
        equates; bitwise operators like AND, OR, NOT; arithmetic operators
        +, -, *, /, \; the relational operators >, <, >=, <=, <>, =; and the
        CVQ function.

        If the [=value] option is omitted, each member of the enumeration is
        assigned an integral value in sequence beginning with the value 0.
        If one or more equates are assigned an explicit value, equates which
        follow are assigned the next value in the sequence. For example:

        ENUM abc
        direction
        count = 8
        scope
        END ENUM

        In the above example, %abc.direction = 0, %abc.count = 8, and
        %abc.scope = 9.

        BITS
        If the BITS option is included, the members are auto-assigned values
        suitable for use as a bit mask, increasing as integral powers of two.
        The first member is auto-assigned the value 0, the next is 1, then
        2, 4, 8, 16, etc. If one or more are assigned an explicit value,
        equates which follow are assigned the next value in the sequence.
        For example:

        ENUM abc BITS
        direction = 1
        count = 8
        scope
        END ENUM

        In the above example, %abc.direction = 1, %abc.count = 8, and
        %abc.scope = 16.

        SINGULAR
        If the SINGULAR option is included, the member name is the complete
        name, without the ENUM name or the period. The equate is referenced
        by just the member name with a percent (%) prepended. For example:

        ENUM abc SINGULAR
        count = 7
        END ENUM

        In the above example, the equate would normally be referenced by
        the compound name %abc.count. However, since it includes the
        SINGULAR option, it is referenced by the simplified name %count.

        AS COM
        If you are using a version of PowerBASIC which creates COM servers,
        you can easily include these equates in your type library; just
        append the words AS COM to the ENUM definition.

        Comment


        • #5
          PB/Win 10 &amp; PB/CC 6 -- What's new?

          ASMDATA / END ASMDATA statements <New>

          Purpose
          Define a block where primitive read-only data is stored.

          Syntax
          ASMDATA <BlockName>
          DB 1, "ABC"$, 0
          DW 2, "XYZ"$$, 0
          DD &H12345678
          DQ 1234567890
          END ASMDATA

          Remarks
          It is frequently convenient to define some data within the code
          section of your program. This data is read-only, so it may never
          be altered. An attempt to do so will result in a GPF (General
          Protection Fault), which will cause termination of your program.
          This type of data is generally accessed only by ASM code.

          Defined Data can be placed inside of a Sub, Function, or Method using
          ASM statements, but there are a number of pitfalls to that technique.
          When debugging, or when using TRACE, PROFILE, DEBUG DISPLAY, ERL,
          ERL$, etc., PowerBASIC must insert special code in various places
          which makes if difficult (if not impossible) for you to access the
          data accurately. You don't know the size of the inserted code, so
          you'll have some difficulty addressing it accurately.

          An ASMDATA block solves that problem entirely. It is designed for
          the sole purpose of defining data, and no extra code or extra data
          is ever inserted for any reason. Data within the block is never
          aligned, so you always know the exact location of each item. The
          ASMDATA block must be located outside of any Sub, Function, or
          Method. However, the BlockName you assign is public, so it may be
          referenced from any place in your program. You may have one block
          in your program, or many.

          By default, all ASMDATA blocks are positioned at the first available
          byte. This allows contiguous blocks to be accessed as though they
          were one larger block. You can align any or all of the blocks
          differently by preceding the block with an #ALIGN metastatement.

          Labels and line numbers are not allowed in an ASMDATA block. If
          you need a reference point to a particular sub-section of your data,
          just split it into two or more blocks, using each BlockName as the
          reference point.

          The only statements allowed within an ASMDATA block are DB, DD, DQ,
          and DW, so they do not need to be preceded by an ASM statement. An
          ANSI string literal expression may be placed in a DB statement, and
          a WIDE (unicode) string literal expression may be placed in a DW
          statement. A string literal expression may consist of quoted string
          literals, string equates, and the concatenation operators (&,+).
          You may also use CHR$(), SPACE$(), and STRING$() if they use only
          literal parameters.

          You can access the address of an ASMDATA block with the CODEPTR()
          function. So, if you create a block named ABC, like this:

          ASMDATA ABC
          DB 5,2,3
          DB 7,8,9
          END ASMDATA

          You could access it something like this:

          AsmVar = CODEPTR(ABC)

          Another option is to access it directly to a CPU register of your
          choice by using one of these opcodes:

          ASM LEA EBX, abc
          ASM MOV EBX, Offset abc

          Or even move it directly to a 32-bit variable:

          ASM MOV AsmVar, Offset abc

          Comment


          • #6
            PB/Win 10 &amp; PB/CC 6 -- What's new?

            Please download the attached sample (VIRTUAL.EXE) which demonstrates
            a Virtual Graphic Window with UserSize. See 500,000 random circles
            generated; Scroll the viewport, Resize the viewport by dragging the
            corners, effective in real-time.



            GRAPHIC SET VIRTUAL
            -------------------
            Purpose
            Expands a graphic target into virtual mode.

            Syntax
            GRAPHIC SET VIRTUAL Width&, Height& [,USERSIZE]

            Remarks
            VIRTUAL mode allows the attached graphic target (control or window)
            to display the contents of a larger virtual window. The physical
            size of the display area is not changed. Instead, the display area
            acts as a smaller viewport, which can be moved around the larger
            virtual window to view one section at a time. The physical size of
            the display area is not changed. If the graphic target is a BitMap,
            no operation is performed, as there would be no display area.

            This statement may be used to change a target to VIRTUAL mode, or to
            change the sizes and UserSize option of an existing VIRTUAL target.

            When executed, a new virtual bitmap of the specified height and
            width is created. Width and Height are always specified in Pixels
            or Dialog Units, depending upon the original window creation. The
            original bitmap is copied, pixel for pixel, at the existing size.
            Any expanded area is filled with the current background color. Your
            program draws to it in the normal fashion for a bitmap of the new size.
            Scroll bars are added so the user can move the viewport to the desired
            section. The size of the viewport is not changed.

            The graphic viewport is initially placed at the upper-left corner
            of the virtual window. If a clip area had been established to create
            margins, it is reset. If scaled coordinates had been established,
            they are also reset, as neither would be appropriate for the altered
            size. You can enable these attributes again with GRAPHIC SCALE or
            GRAPHIC SET CLIP, based upon the new size of the drawing area. You
            can retrieve the size of the virtual drawing area, at any time, with
            GRAPHIC GET CANVAS.

            The graphic viewport can be moved by clicking the scrollbars, or by
            moving the mouse wheel to alter the vertical position. Depressing
            the control key, along with the mouse wheel, alters the horizontal
            position. In addition, the cursor movement keys (Left, Right, Up,
            Down, PageUp, PageDown, Home, End) may also be used for this purpose.

            VIRTUAL mode is quite similar to AUTOSIZE mode. Both create a
            virtual window which is the target of your drawing and text printing
            operations. The difference is the way in which they are displayed.
            VIRTUAL displays a viewport, smaller than the virtual window, which
            can be moved to various positions. This allows the user to view one
            selected section at a time. AUTOSIZE displays the entire virtual
            window, all of the time, by stretching or condensing it as needed.

            If you add the USERSIZE option, an attached graphic window is
            displayed with a thick frame, which allows the user to "drag" the
            edges to a new size at any time. This option is not appropriate for
            a graphic control, and is ignored in that case.

            Generally speaking, it is not advisable to enable ScrollText mode on
            a virtual graphic window, as the display may be confusing to the user.
            Attached Files

            Comment


            • #7
              PB/Win 10 &amp; PB/CC 6 -- What's new?

              PowerTime Object

              Purpose
              A PowerTime Object contains a date and time value, allowing easy
              calculations. The internal representation emulates the Windows
              FILETIME structure as a quad-integer. This value represents the
              number of 100-nanosecond intervals since January 1, 1601. A
              nanosecond is one-billionth of a second.

              You create a PowerTime object the same way you create other objects,
              but using a predefined internal class and a predefined internal
              interface.

              LOCAL MyTime AS IPowerTime
              LET MyTime = CLASS "PowerTime"

              Once you have created a PowerTime object, you can manipulate it
              using the member methods. The IPowerTime interface is DUAL -- member
              methods may be referenced using either Direct or Dispatch form.

              Remarks
              The Dispatch ID (DispID) for each member method is displayed within
              angle brackets.


              <>===================<>
              || PowerTime Methods ||
              <>===================<>


              AddDays <1> (ByVal Days&)
              -------------------------
              Adds the specified number of days to the value of this object.
              You can subtract days by using a negative number.


              AddHours <2> (ByVal Hours&)
              ---------------------------
              Adds the specified number of hours to the value of this object.
              You can subtract hours by using a negative number.


              AddMinutes <3> (ByVal Minutes&)
              -------------------------------
              Adds the specified number of minutes to the value of this object.
              You can subtract minutes by using a negative number.


              AddMonths <4> (ByVal Months&)
              -----------------------------
              Adds the specified number of months to the value of this object.
              You can subtract months by using a negative number.


              AddMSeconds <5> (ByVal Milliseconds&)
              -------------------------------------
              Adds the specified number of milliseconds to the value of this
              object. You can subtract milliseconds by using a negative number.


              AddSeconds <6> (ByVal Seconds&)
              -------------------------------
              Adds the specified number of seconds to the value of this object.
              You can subtract seconds by using a negative number.


              AddTicks <7> (ByVal Ticks&)
              ---------------------------
              Adds the specified number of ticks to the value of this object.
              You can subtract ticks by using a negative number.


              AddYears <8> (ByVal Years&)
              ---------------------------
              Adds the specified number of years to the value of this object.
              You can subtract years by using a negative number.


              DateString <10> (OPT ByVal LCID&) AS WString
              --------------------------------------------
              Returns the Date component of the PowerTime object expressed as a
              string. The date is formatted for the locale, based upon the LCID&
              parameter. If LCID& is zero, or not given, the default LCID for the
              user is substituted.


              DateStringLong <11> (OPT ByVal LCID&) AS WString
              ------------------------------------------------
              Returns the Date component of the PowerTime object, expressed as a
              string, with a full alphabetic month name. The date is formatted for
              the locale, based upon the LCID& parameter. If LCID& is zero, or not
              given, the default LCID for the user is substituted.


              Day <13> () AS Long
              -------------------
              Returns the Day component of the PowerTime object. It is a numeric
              value in the range of 1-31.


              DayOfWeek <14> () AS Long
              -------------------------
              Returns the Day-of-Week component of the PowerTime object. It is a
              numeric value in the range of 0-6 (representing Sunday through
              Saturday).


              DayOfWeekString <15> (OPT ByVal LCID&) AS WString
              -------------------------------------------------
              Returns the Day-of-Week name of the PowerTime object, expressed as
              a string (Sunday, Monday...). The day name is appropriate for the
              locale, based upon the LCID& parameter. If LCID& is zero, or not
              given, the default LCID for the user is substituted.


              DaysInMonth <16> () AS Long
              ---------------------------
              Returns the number of days which comprise the month of the date
              of the PowerTime object. This is a numeric value in the range of
              28-31.


              PROPERTY GET FileTime <18> () AS Quad
              -------------------------------------
              Returns a Quad-Integer value of the PowerTime object as a FileTime.


              PROPERTY SET FileTime <18> () = Quad
              ------------------------------------
              The FileTime Quad-Integer value specified by the parameter is assigned
              as the PowerTime object value.


              Hour <19> () as Long
              --------------------
              Returns the Hour component of the PowerTime object. It is a
              numeric value in the range of 0-23.


              IsLeapYear <20> () as Long
              --------------------------
              Returns true/false (-1/0) to tell if the PowerTime object year is
              a leap year.


              Minute <21> () as Long
              ----------------------
              Returns the Minute component of the PowerTime object. This is a
              numeric value in the range of 0-59.


              Month <22> () as Long
              ---------------------
              Returns the Month component of the PowerTime object. This is a
              numeric value in the range of 1-12.


              MonthString <23> () AS String
              -----------------------------
              Returns the Month component of the PowerTime object, expressed as
              a string (January, February...).


              MSecond <24> () as Long
              -----------------------
              Returns the millisecond component of the PowerTime object. This is
              a numeric value in the range of 0-999.


              NewDate <25> (ByVal Year&, Opt ByVal Month&, Opt ByVal Day&)
              ------------------------------------------------------------
              The date component of the PowerTime object is assigned a new value
              based upon the specified parameters. The time component is unchanged.


              NewTime <26> (ByVal Hour&, Opt ByVal Minute&, Opt ByVal Second&, Opt ByVal MSecond&, Opt ByVal Tick&)
              -----------------------------------------------------------------------------------------------------
              The time component of the PowerTime object is assigned a new value
              based upon the specified parameters. The date component is unchanged.


              Now <27> ()
              -----------
              The current local date and time on this computer is assigned to this
              PowerTime object.


              NowUTC <28> ()
              --------------
              The current Coordinated Universal date and time (UTC) is assigned to
              this PowerTime object.


              Second <29> () as Long
              ----------------------
              Returns the Second component of the PowerTime object. This is a
              numeric value in the range of 0-59.


              Tick <30> () as Long
              --------------------
              Returns the Tick component of the PowerTime object. This is a
              numeric value in the range of 0-999.


              TimeString <31> () AS WString
              -----------------------------
              Returns the Time component of the PowerTime object expressed as a
              string. The time is formated as hh:mm AM/PM.


              TimeString24 <32> () AS WString
              -------------------------------
              Returns the Time component of the PowerTime object expressed as a
              string. The time is formated as hh:mm in 24-hour notation.


              TimeStringFull <33> () AS WString
              ---------------------------------
              Returns the Time component of the PowerTime object expressed as a
              string. The time is formated as hh:mm:ss.tt in 24-hour notation.


              Today <35> ()
              -------------
              The current local date on this computer is assigned to this
              PowerTime object. This is suitable for applications that work
              with dates only.


              ToLocalTime <36> ()
              -------------------
              The PowerTime object is converted to local time. It is assumed that
              the previous value was in Coordinated Universal Time (UTC).


              ToUTC <37> ()
              -------------
              The PowerTime object is converted to Coordinated Universal Time (UTC).
              It is assumed that previous value was in local time.


              Year <40> () as Long
              --------------------
              Returns the Year component of the PowerTime object as a numeric
              value.


              The Power Changes Everything.

              Comment


              • #8
                PB/Win 10 &amp; PB/CC 6 -- What's new?

                FASTPROC...END FASTPROC statements

                Purpose
                Define a FastProc code section.

                Syntax
                FASTPROC ProcName [([arguments])] [THREADSAFE] [AS LONG]
                statements...
                END FASTPROC [= return value]

                Remarks
                A Fast Procedure (FASTPROC) is a highly simplified form of SUB
                or FUNCTION which executes much faster than its fully-featured
                counterparts. It allows a maximum of two BYVAL LONG arguments,
                and may optionally return a LONG result. The arguments are always
                processed as register variables for maximum execution speed. No
                stack frame is ever created, so there are other limitations detailed
                below. The programmer may then decide when it is appropriate to
                accept these trade-offs in exchange for maximum efficiency.

                All executable code must reside in a Sub, Function, Method, FastProc,
                or Property block. You cannot define a procedure inside another
                procedure. A FASTPROC is a subroutine-like block of statements which
                is invoked with the CALL statement. A FASTPROC may also be invoked
                without the word CALL, which is then implied. If the CALL word is
                omitted, the parentheses around the argument list must also be omitted.

                The name of the Sub. ProcName must be unique: no variable, Function,
                Sub, Method, FastProc, Property or label can share the same name.

                THREADSAFE
                If you include the option THREADSAFE, PowerBASIC automatically
                establishes a semaphore which allows only one thread to execute it
                at a time. Others must wait until the first thread exits the
                THREADSAFE procedure before they are allowed to begin.

                Limitations
                Most of the limitations of a FASTPROC stem from the fact that no
                stack frame is created.

                * A maximum of two parameters are allowed, and they must be defined
                as BYVAL LONG integers. An optional return value, if used, must
                be defined as LONG integer.

                * LOCAL variables are not available because there is no stack frame.
                This includes Register variables, which are by definition, Local
                variables. Instead, one or two parameters are automatically
                given status as Register Variables. By default, all new variables
                are assigned STATIC scope.

                * ON ERROR GOTO, RESUME, and TRY blocks are not available. You
                should explicitly test for errors with IF ERR THEN...

                * DATA and READ$ are not available.

                * FUNCNAME$ is not available.

                * COMMON, IMPORT, and EXPORT options are not available.

                See also
                CALL, DECLARE, EXIT FASTPROC, FUNCTION, GLOBAL, GOSUB, LOCAL,
                STATIC, THREADSAFE


                The Power Changes Everything.

                Comment


                • #9
                  PB/Win 10 &amp; PB/CC 6 -- What's new?

                  PREFIX...END PREFIX statements

                  Purpose
                  Executes a series of statements, each of which utilizes pre-defined source code.

                  Syntax
                  PREFIX "source code"
                  ...additional statements
                  END PREFIX

                  Remarks
                  PREFIX...END PREFIX statements enclose a set of source code lines.
                  When compiled, each line in the set is automatically prefixed with
                  additional pre-determined source code. This can reduce repetitive
                  typing and reduce the risk of typing errors. For example:

                  Code:
                  PREFIX...END PREFIX
                  --------------------
                  
                  PREFIX "MyObject."
                    Init(xx) 
                    Sleep(2) 
                  END PREFIX
                  
                  Compiles as:
                  MyObject.Init(xx)
                  MyObject.Sleep(2)
                          
                  PREFIX "ASM"
                    Mov  Eax, Ebx                 
                    Mov  Ecx, &H14                
                    IMul Eax, Esi 
                  END PREFIX
                  
                  Compiles as:
                  ASM Mov  Eax, Ebx
                  ASM Mov  Ecx, &H14
                  ASM IMul  Eax, Esi
                  If the "source code" prefix refers to an object variable or a UDT
                  structure variable, be sure it ends with a period (.) to reference
                  members of that item.

                  PREFIX...END PREFIX structures may not be nested.

                  Comment


                  • #10
                    PB/Win 10 &amp; PB/CC 6 -- What's new?

                    STRINGBUILDER Object

                    Purpose
                    The StringBuilder object offers the ability to concatenate many
                    string sections at a very high level of performance. The speed of
                    execution is particularly noticeable when the concatenation is
                    performed in many separate operations over a period of time. If
                    all of the string sections are known and available at once, the
                    use of the BUILD$() function could be a better choice. However,
                    both options offer a very large boost as compared to the standard
                    concatenation operators (& or +). In addition to concatenation,
                    the StringBuilder Class also offers a few additional string
                    operations to assist in building the string.

                    Remarks
                    There are two forms of the StringBuilder object, one for ANSI strings,
                    and one for WIDE (unicode) strings. While they could have been
                    combined into a single hybrid object, that would have added additional
                    overhead not acceptable for PowerBASIC. To concatenate ANSI strings,
                    use the StringBuilderA class and the IStringBuilderA interface. To
                    concatenate WIDE (unicode) strings, use the StringBuilderW class and
                    the IStringBuilderW interface. The methods and mode of operation are
                    identical for both forms.

                    If you choose the ANSI form, parameter strings must be ANSI, and
                    result strings will be ANSI. With the WIDE (unicode) form, parameter
                    strings must be wide, and result strings will be wide. Keep those
                    requirements in mind when reviewing the following method definitions.
                    The Dispatch ID (DispID) for each member method is displayed within
                    angle brackets.

                    When you create a StringBuilder object, a dynamic string buffer is
                    created to hold the target string. If you know the size of the
                    result string (or even an approximation), it's usually prudent to
                    use the CAPACITY method first, to establish a size at least as large
                    as the final string. If it's not known, PowerBASIC will try to make
                    appropriate decisions for you. Once the object is created, the ADD
                    method is used to append string sections as many times as necessary.
                    Finally, the STRING method is used to extract the combined items.


                    StringBuilder Methods/Properties
                    ================================

                    ADD (PowerString$) Method<1>
                    ------------------
                    The PowerString parameter is appended to the string held in the
                    StringBuilder object. If the internal string buffer overflows,
                    PowerBASIC will automatically extend it to an appropriate size.
                    If a necessary buffer extension fails, an HResult of E_OUTOFMEMORY
                    (&H8007000E) is returned, and an Object Error (99) is generated.


                    CAPACITY () AS Long Get Property<2>
                    -------------------
                    The size of the internal string buffer is retrieved and returned
                    to the caller. The size is the number of characters which can be
                    stored without further expansion.


                    CAPACITY () = Long Set Property<2>
                    ------------------
                    The internal string buffer is expanded to the number of characters
                    specified by the Long Integer. If the new capacity is smaller or
                    equal to the current capacity, no operation is performed.


                    CHAR (Index&) AS Long Get Property<3>
                    ---------------------
                    The numeric character code of the character at the position Index&
                    is retrieved and returned to the caller. Index&=1 for the first
                    character, 2 for the second, etc. If Index& is beyond the current
                    length of the string, the value -1 is returned.


                    CHAR (Index&) = Long Set Property<3>
                    --------------------
                    The character at the position Index& is changed to that specified
                    by the Long Integer character code. Index&=1 for the first
                    character, 2 for the second, etc.


                    CLEAR Method<4>
                    -----
                    All data in the object is erased.


                    DELETE (Index&, Count&) Method<5>
                    -----------------------
                    Count& characters are removed starting at the position given by
                    Index&. Index&=1 for the first character, 2 for the second, etc.


                    INSERT (PowerString$, Index&) Method<6>
                    -----------------------------
                    The PowerString parameter is inserted in the string starting at
                    the position given by Index&. Index&=1 for the first character,
                    2 for the second, etc. If Index& is beyond the current length of
                    the string, no operation is performed.


                    LEN () AS Long Method<7>
                    --------------
                    The number of characters currently stored in the object is returned
                    as a long integer value.


                    STRING AS String Method<8>
                    ----------------
                    The string stored in the object is returned to the caller. This
                    string will contain LEN characters.

                    Comment


                    • #11
                      PB/Win 10 &amp; PB/CC 6 -- What's new?

                      COLLECTION Object Group

                      A collection object is a set of items which can be referred to as a
                      unit. It provides a convenient way to refer to a related group of
                      items as a single object. The items in a collection need only be
                      related by the fact that they exist in the collection. They do not
                      have to share the same data type.

                      You create a collection the same way you create other objects, but
                      using a predefined internal class and a predefined internal interface.

                      LOCAL Collect AS IPowerCollection
                      LET Collect = CLASS "PowerCollection"

                      Once you have created a collection object, you can manipulate it
                      using the member methods. Each data item in the set is stored as a
                      VARIANT variable, which may contain any valid data type (numeric,
                      string, UDT, object, etc.). Collection interfaces are DUAL -- member
                      methods may be referenced using either Direct or Dispatch form.

                      While the collection object expects to receive your data items as
                      variant variables, you can take advantage of the auto-conversion
                      options in PowerBASIC. If a Variant parameter is expected, and you
                      pass a single variable instead, PowerBASIC will automatically
                      convert it with no intervention needed on your part.

                      Very often, it's convenient to create a collection of user defined
                      types (UDT). While a variant may not normally contain a UDT,
                      PowerBASIC offers a special methodology to do so. At programmer
                      direction, a TYPE may be assigned to a variant (as a byte string)
                      by using:

                      [LET] VrntVar = TypeVar AS STRING

                      In the same manner, a UDT argument can be auto-converted to the
                      variant type by appending AS STRING:

                      CollObj.Add(Key$$, UDTVar AS STRING)

                      The data contained in the User-Defined Type variable (UDTVar) is
                      stored in the variant argument as a dynamic string of bytes
                      (vt_bstr). When the collection object retrieves that UDT data,
                      it understands the content and handles it accurately. This
                      special technique offers ease of coding and much improved
                      execution speed. If you like, you can use the same sort of
                      functionality in your own PowerBASIC code. However, you should
                      keep in mind that other programming languages may not understand
                      this technique, so it should be limited to PowerBASIC applications.



                      <>==================<>
                      || Power Collection ||
                      <>==================<>

                      Purpose
                      A Power Collection creates a set of data items, each of which is
                      associated with an alpha-numeric string key which you define. The
                      data item is passed and stored as a variant, while the key is passed
                      and stored as a wide (unicode) string. You can retrieve these data
                      items directly by using their key, by their position in the collection,
                      or sequentially in ascending or descending sequence.

                      Syntax
                      The CLASS is "PowerCollection"
                      The INTERFACE is IPowerCollection (a DUAL interface)
                      <ObjectVar>.membername(params)
                      RetVal = <ObjectVar>.membername(params)
                      <ObjectVar>.membername(params) TO ReturnVariable

                      Remarks
                      Items in a PowerCollection may be retrieved by their key using the
                      ITEM method. They may be retrieved sequentially using the NEXT or
                      PREVIOUS method. Each key in a PowerCollection must be unique.

                      Keys in a PowerCollection are case-sensitive. To acces the keys in
                      a case-insensitive manner, you must create and retrieve all keys as
                      either upper case or lower case, but not mixed.

                      The Dispatch ID (DispID) for each member method is displayed within
                      angle brackets.


                      Power Collection Methods
                      ========================

                      ADD <3> (PowerKey AS WString, PowerItem AS Variant)
                      ---------------------------------------------------
                      The PowerItem variant is added to the end of the PowerCollection.
                      It is associated with the PowerKey string for later retrieval. If
                      the operation was successful, an HResult of S_OK (0) is returned.
                      If it fails because of a duplicate key, an HResult of E_DUPLICATEKEY
                      (&H800A01C9) is returned, and an Object Error (99) is generated.


                      CLEAR <4>
                      ---------
                      All PowerKeys and PowerItems are removed from the PowerCollection.


                      CONTAINS <5> (PowerKey AS WString) AS Long
                      ------------------------------------------
                      The PowerCollection is scanned to determine if the specified
                      PowerKey is present. If found, the Index number of this Item
                      (range of 1 - COUNT) is returned. This value will always evaluate
                      as true. If not found, the value false (0) is returned.


                      COUNT <6> AS Long
                      -----------------
                      The number of data items currently contained in the PowerCollection
                      is returned to the caller.


                      ENTRY <7> (Index AS Long, OUT PowerKey as WString, OUT PowerItem as Variant)
                      ----------------------------------------------------------------------------
                      The PowerCollection entry specified by the Index number is returned
                      to the caller in the two specified OUT parameters. If the index number
                      is less than one, or greater than the item count, the variant returned
                      will be of type empty (VT_EMPTY), and the OBJRESULT will be %S_FALSE (1).


                      FIRST <1> AS Long
                      -----------------
                      The current INDEX for the PowerCOLLECTION is set to one (1), so
                      that subsequent references to the NEXT method will access member
                      items from the beginning. The previous value of the INDEX is
                      returned to the caller.


                      INDEX <8> (Index AS Long) AS Long
                      ---------------------------------
                      The current INDEX for the PowerCOLLECTION is set to the specified
                      index number. If the parameter is less than one, or greater than
                      the current count of data items, the INDEX is not changed. The
                      previous value of the INDEX is returned to the caller.

                      IndexVar& = ObjectVar.INDEX(0)

                      The above example retrieves the current index number, without
                      changing it, and assigns it to the variable IndexVar&.


                      ITEM <9> (PowerKey AS WString) AS Variant
                      -----------------------------------------
                      The PowerItem associated with the specified PowerKey is returned.
                      If the specified key is not found, the variant returned will be
                      of type empty (VT_EMPTY), and the OBJRESULT will be %S_FALSE (1).


                      LAST <10> AS Long
                      ----------------
                      The current INDEX for the PowerCOLLECTION is set to the last item
                      so that subsequent references to the PREVIOUS method will access
                      member items from the end. The previous value of the INDEX is
                      returned to the caller.


                      NEXT <2> AS Variant
                      --------------------
                      The NEXT method allows the PowerCollection data items to be retrieved
                      sequentially. Each time NEXT is referenced, the data item at the
                      position specified by the INDEX is returned to the caller, and the
                      INDEX is incremented. If the operation is successful, the OBJRESULT
                      is set to %S_OK (0). When there are no more data items to retrieve,
                      the OBJRESULT is set to %S_FALSE (1).


                      PREVIOUS <11> AS Variant
                      ------------------------
                      The PREVIOUS method allows the PowerCollection data items to be
                      retrieved sequentially. Each time PREVIOUS is referenced, the data
                      item at the position specified by the INDEX is returned to the caller,
                      and the INDEX is decremented. If the operation is successful, the
                      OBJRESULT is set to %S_OK (0). When there are no more data items to
                      retrieve, the OBJRESULT is set to %S_FALSE (1).


                      REMOVE <12> (PowerKey AS WString)
                      ---------------------------------
                      The specified PowerKey, and the PowerItem associated with it, are
                      removed from the PowerCollection. The index number of each data item
                      past the removed item is decremented by one. If the requested
                      PowerKey is not found, OBJRESULT returns %S_FALSE (1) and no operation
                      is performed.


                      REPLACE <13> (PowerKey AS WString, PowerItem AS Variant)
                      --------------------------------------------------------
                      The PowerItem associated with the specified PowerKey is replaced by
                      the new specified PowerItem. If the requested PowerKey is not found,
                      OBJRESULT returns %S_FALSE (1) and no operation is performed.


                      SORT <14> (Flags AS Long)
                      -------------------------
                      The data items in the PowerCollection are sorted based upon the text
                      in the associated PowerKeys. If the parameter Flags is zero(0), the
                      items are sorted in ascending sequence. If one (1), the items are
                      sorted in descending sequence.

                      Comment


                      • #12
                        GRAPHIC SET AUTOSIZE
                        --------------------
                        Purpose
                        Expands a graphic target into autosize mode.

                        Syntax
                        GRAPHIC SET AUTOSIZE Width, Height [,USERSIZE]

                        Remarks
                        AUTOSIZE mode allows the attached graphic target (control or window)
                        to display the contents of a virtual window, which may be larger or
                        smaller. The entire contents of the virtual window are always
                        displayed on the screen, so the image is stretched or condensed to
                        fit properly. The physical size of the display area is not changed.
                        If the graphic target is a BitMap, no operation is performed, as
                        there is no display area.

                        This statement may be used to change a target to AUTOSIZE mode, or to
                        change the sizes and UserSize option of an existing AUTOSIZE target.

                        When executed, a new virtual bitmap of the specified height and
                        width is created. Width and Height are always specified in Pixels
                        or Dialog Units, depending upon the original window creation. The
                        new virtual bitmap is immediately filled with the original bitmap,
                        but stretched or condensed to fit. This is done to avoid flashing
                        effects which sometimes occur with a brief color change. Your
                        program may now draw to the new bitmap in the normal fashion for a
                        bitmap of the new size.

                        If a clip area had been established to create margins, it is reset.
                        If scaled coordinates had been established, they are also reset, as
                        neither would be appropriate for the altered size. You can enable
                        these attributes again with GRAPHIC SCALE or GRAPHIC SET CLIP, based
                        upon the new size of the drawing area. You can retrieve the size of
                        the virtual drawing area, at any time, with GRAPHIC GET CANVAS.

                        AUTOSIZE mode is quite similar to VIRTUAL mode. Both create a
                        virtual window which is the target of your drawing and text printing
                        operations. The difference is the way in which they are displayed.
                        VIRTUAL displays a viewport, smaller than the virtual window, which
                        can be moved to various positions. This allows the user to view one
                        selected section at a time. AUTOSIZE displays the entire virtual
                        window, all of the time, by stretching or condensing it as needed.

                        If you add the USERSIZE option, an attached graphic window is
                        displayed with a thick frame, which allows the user to "drag" the
                        edges to a new size at any time. This option is not appropriate for
                        a graphic control, and is ignored in that case.

                        Comment


                        • #13
                          <>=====================<>
                          || LinkList Collection ||
                          <>=====================<>

                          Purpose
                          A Linked List Collection is an ordered set of data items, which
                          are accessed by their position in the list rather than by an
                          alphanumeric string key. Each data item is passed and stored as
                          a variant variable. You can retrieve these data items by their
                          position number, or sequentially in ascending or descending sequence.

                          Syntax
                          The CLASS is "LinkListCollection"
                          The INTERFACE is ILinkListCollection (a DUAL interface)
                          <ObjectVar>.membername(params)
                          RetVal = <ObjectVar>.membername(params)
                          <ObjectVar>.membername(params) TO ReturnVariable

                          Remarks
                          Items in a LinkListCollection may be retrieved by their position
                          number using the ITEM method. They may be retrieved sequentially
                          using the NEXT or PREVIOUS methods.

                          The Dispatch ID (DispID) for each member method is displayed within
                          angle brackets.


                          LinkList Collection Methods
                          ===========================

                          ADD <3> (PowerItem AS Variant)
                          ------------------------------
                          The PowerItem variant is added to the end of the LinkListCollection.


                          CLEAR <4>
                          ---------
                          All PowerItems are removed from the LinkListCollection.


                          COUNT <5> AS Long
                          -----------------
                          The number of data items currently contained in the LinkListCollection
                          is returned to the caller.


                          FIRST <1> AS Long
                          -----------------
                          The current INDEX for the LinkListCOLLECTION is set to one (1), so
                          that subsequent references to the NEXT method will access member
                          items from the beginning. The previous value of the INDEX is
                          returned to the caller.


                          INDEX <6> (Index AS Long) AS Long
                          ---------------------------------
                          The current INDEX for the LinkListCOLLECTION is set to the specified
                          index number. If the parameter is less than one, or greater than
                          the current count of data items, the INDEX is not changed. The
                          previous value of the INDEX is returned to the caller.

                          IndexVar& = ObjectVar.INDEX(0)

                          The above example retrieves the current index number, without
                          changing it, and assigns it to the variable IndexVar&.


                          INSERT <7> (Index AS Long, PowerItem AS Variant)
                          ------------------------------------------------
                          The PowerItem variant is added to the collection at the position
                          specified by the Index. If the index number is less than one, or
                          greater than the count, the item is added to the end of the list.


                          ITEM <8> (Index AS Long) AS Variant
                          -----------------------------------
                          The PowerItem at the position specified by Index is returned. If
                          the specified item is not present, the variant returned will be of
                          type empty (VT_EMPTY), and the OBJRESULT will be %S_FALSE (1).


                          LAST <9> AS Long
                          ----------------
                          The current INDEX for the LinkListCOLLECTION is set to the last item
                          so that subsequent references to the PREVIOUS method will access
                          member items from the end. The previous value of the INDEX is
                          returned to the caller.


                          NEXT <2> AS Variant
                          -------------------
                          The NEXT method allows the LinkListCollection data items to be
                          retrieved sequentially. Each time NEXT is referenced, the data item
                          at the position specified by the INDEX is returned to the caller,
                          and the INDEX is incremented. If the operation is successful, the
                          OBJRESULT is set to %S_OK (0). When there are no more data items to
                          retrieve, the OBJRESULT is set to %S_FALSE (1).


                          PREVIOUS <10> AS Variant
                          ------------------------
                          The PREVIOUS method allows the LinkListCollection data items to be
                          retrieved sequentially. Each time PREVIOUS is referenced, the data
                          item at the position specified by the INDEX is returned to the caller,
                          and the INDEX is decremented. If the operation is successful, the
                          OBJRESULT is set to %S_OK (0). When there are no more data items to
                          retrieve, the OBJRESULT is set to %S_FALSE (1).


                          REMOVE <11> (Index AS Long)
                          ---------------------------
                          The PowerItem at the position specified by Index is removed from the
                          LinkListCollection. The index number of each data item past the
                          removed item is decremented by one. If the requested item is not
                          present, OBJRESULT returns %S_FALSE (1) and no operation is performed.


                          REPLACE <12> (Index AS Long, PowerItem AS Variant)
                          --------------------------------------------------
                          The PowerItem at the position specified by Index is replaced by
                          the new specified PowerItem. If the requested PowerItem is not
                          present, OBJRESULT returns %S_FALSE (1) and no operation is performed.

                          Comment


                          • #14
                            Stack Collection

                            <>==================<>
                            || Stack Collection ||
                            <>==================<>

                            Purpose
                            A Stack Collection is an ordered set of data items, which are
                            accessed on a LIFO (Last-In / First-Out) basis. This collection
                            follows the same algorithm as the machine stack on your Intel CPU.
                            Each data item is passed and stored as a variant variable, using
                            the PUSH and POP methods.

                            Syntax
                            The CLASS is "StackCollection"
                            The INTERFACE is IStackCollection (a DUAL interface)

                            <ObjectVar>.membername(params)
                            RetVal = <ObjectVar>.membername(params)
                            <ObjectVar>.membername(params) TO ReturnVariable

                            Remarks
                            The Dispatch ID (DispID) for each member method is displayed within
                            angle brackets.


                            Stack Collection Methods
                            ========================

                            CLEAR <1>
                            ---------
                            All PowerItems are removed from the StackCollection.


                            COUNT <2> AS Long
                            -----------------
                            The number of data items currently contained in the StackCollection
                            is returned to the caller.


                            POP <3> AS Variant
                            ------------------
                            The PowerItem at the "Stack-Top" (the item most recently added) is
                            retrieved and returned to the caller. When there are no more data
                            items to retrieve, the variant returned will be of type empty
                            (VT_EMPTY), and the OBJRESULT will be %S_FALSE (1).


                            PUSH <4> (PowerItem AS Variant)
                            -------------------------------
                            The specified PowerItem is added to the StackCollection at the
                            "Stack-Top" position.

                            Comment


                            • #15
                              SHRINK$ function

                              Purpose
                              Shrink a string to use a consistent single character delimiter.

                              Syntax
                              NewString$ = SHRINK$(OldString$)
                              NewString$ = SHRINK$(OldString$, Mask$)

                              Remarks
                              The purpose of this function is to create a string with consecutive
                              data items (words) separated by a consistent single character. This
                              makes it very straightforward to parse the results as needed.

                              In the first form, all leading spaces and trailing spaces are removed
                              entirely. All occurrences of two or more spaces are changed to a
                              single space. Therefore, the new string returned consists of zero
                              or more words, each separated by a single space character.

                              In the second form, Mask$ defines one or more delimter characters
                              to shrink. All leading and trailing mask characters are removed
                              entirely. All occurrences of one or more mask characters are
                              replaced with the first character of Mask$. Therefore, the new
                              string returned consists of zero or more words, each separated by
                              the character found in the first position of Mask$.

                              WhiteSpace is generally defined as the four common non-printing
                              characters: Space, Tab, Carriage-Return, and Line-Feed. This is
                              pre-defined in PowerBASIC as string equates for your convenience.
                              The ANSI version is named $WHITESPACE, while the WIDE version is
                              $$WHITESPACE. This equate is particularly well suited to be used
                              as Mask$ in this function.

                              See also
                              INSTR, LTRIM$, REMOVE$, REPLACE, RTRIM$, TRIM$

                              Comment


                              • #16
                                Queue Collection
                                ================


                                Purpose
                                A Queue Collection is an ordered set of data items, which are
                                accessed on a FIFO (First-In / First-Out) basis. Each data item
                                is passed and stored as a variant variable, using the ENQUEUE and
                                DEQUEUE methods.

                                Syntax
                                The CLASS is "QueueCollection"
                                The INTERFACE is IQueueCollection (a DUAL interface)
                                <ObjectVar>.membername(params)
                                RetVal = <ObjectVar>.membername(params)
                                <ObjectVar>.membername(params) TO ReturnVariable

                                Remarks
                                The Dispatch ID (DispID) for each member method is displayed within
                                angle brackets.


                                Queue Collection Methods
                                ========================

                                CLEAR <1>
                                ---------
                                All PowerItems are removed from the QueueCollection.


                                COUNT <2> AS Long
                                -----------------
                                The number of data items currently contained in the QueueCollection
                                is returned to the caller.


                                DEQUEUE <3> AS Variant
                                ----------------------
                                The PowerItem at the "oldest" position is retrieved and returned to
                                the caller. When there are no more data items to retrieve, the
                                variant returned will be of type empty (VT_EMPTY), and the OBJRESULT
                                will be %S_FALSE (1).


                                ENQUEUE <4> (PowerItem AS Variant)
                                ----------------------------------
                                The specified PowerItem is added to the QueueCollection at the
                                "newest" position.

                                Comment


                                • #17
                                  #UNIQUE metastatement

                                  #UNIQUE metastatement

                                  Purpose
                                  Specifies whether unique variable names are required.

                                  Syntax
                                  #UNIQUE VAR [ON|OFF]

                                  Remarks
                                  By default (#UNIQUE VAR OFF), it is possible to use the same name
                                  for more than one variable in your program. For example, you might
                                  use abc%, abc#, and abc$ in the same function using default typing
                                  defined by the Type ID character. You could even create a local
                                  variable named "counters" and a global variable also named "counters".

                                  So, when you reference a variable name in your program, which variable
                                  is actually used? Depending upon the location of the reference, the
                                  compiler chooses the variable with the smallest scope. The precedence
                                  of variable scopes is:

                                  1- Local or Static
                                  2- Instance
                                  3- Global or Threaded

                                  When #UNIQUE VAR is OFF, PowerBASIC first tries to find a LOCAL or
                                  STATIC. Next, an INSTANCE, and finally a GLOBAL or THREADED. It
                                  selects the first one it finds, in that sequence. Of course, you
                                  cannot use the same name for a LOCAL and a STATIC, unless you use
                                  a Type ID character to differentiate them. You can never use the
                                  same name for a GLOBAL and a THREADED, as it would be impossible to
                                  tell them apart. While this offers the most flexibility, it can be
                                  confusing, and can lead to the creation of insidious, hard-to-find
                                  errors in your program. When you reference the wrong variable by
                                  accident, the results can be disastrous.

                                  If #UNIQUE VAR is enabled, PowerBASIC will require that all variable
                                  names be unique. The can make your job a good deal easier, as it
                                  removes the ambiguity found with identifier reuse. There are a few
                                  exceptions to the uniqueness rule, which are designed to improve
                                  readability in your code:

                                  1- Local, Static, and Parameter names may be reused in other
                                  Subs, Functions, and Methods.
                                  2- Instance names may reused in other Classes.
                                  3- Scalar and array names may co-exist if they they are the
                                  same data type and scope.

                                  Comment


                                  • #18
                                    %PB_COMPILETIME numeric equate

                                    %PB_COMPILETIME numeric equate

                                    Purpose
                                    Helps to determine the date/time of compilation.

                                    Remarks
                                    Each time you compile your program, this equate is filled with
                                    the current date and time of the compilation in PowerTime binary
                                    format. You can use the PowerTIME Class to convert it to a text
                                    equivalent for use in your application.

                                    LOCAL Built AS IPowerTime
                                    LET Built = CLASS "PowerTime"
                                    Built.FileTime = %PB_COMPILETIME
                                    MSGBOX Built.DateString
                                    MSGBOX Built.TimeString

                                    Comment


                                    • #19
                                      Con.waitkey$

                                      CON.WAITKEY$
                                      ------------
                                      Syntax: StringVar$ = CON.WAITKEY$
                                      StringVar$ = CON.WAITKEY$([KeyMask$] [,TimeOut&])
                                      CON.WAITKEY$ [TO StringVar$]
                                      CON.WAITKEY$([KeyMask$] [,TimeOut&]) [TO StringVar$]

                                      Legacy: WAITKEY$
                                      variable$ = WAITKEY$

                                      Reads a character, extended key, or mouse event from the console
                                      without echoing anything to the screen. If no data is available,
                                      CON.WAITKEY$ will wait for an event to occur. It is very similar to
                                      CON.INKEY$, except that it waits for input to be available. While
                                      waiting, time slices are released to the operating system to reduce
                                      CPU load.

                                      CON.WAITKEY$ returns a string of one or two characters if a key was
                                      pressed. It returns a string of four characters for a mouse event,
                                      but only if mouse event trapping is enabled. CON.WAITKEY$ will always
                                      read keys from the keyboard, regardless of STDIN redirection status.

                                      If the optional KeyMask$ expression is included, it tells CON.WAITKEY$
                                      to recognize only a limited set of key or mouse events. KeyMask$ may
                                      include any number of Sub-Masks, one for each key or mouse event to
                                      observe. For example, CON.WAITKEY$("YyNn") will recognize upper-case
                                      or lower-case Y or N (for yes/no answers), while any other key or
                                      mouse event will be ignored. If KeyMask$ is omitted, or evaluates to
                                      a zero-length string, any key event or mouse event will be recognized.

                                      If the optional TimeOut& expression is included, it tells CON.WAITKEY$
                                      the maximum number of milliseconds to wait for a key or mouse event.
                                      CON.WAITKEY$(5000) will wait a maximum of 5 seconds. The specified
                                      TimeOut period will only be approximate, so you should not rely upon
                                      precision accuracy. If the TimeOut period is exceeded, a zero-length
                                      string is returned. If the TimeOut& parameter is omitted, or evaluates
                                      to zero (0), it will wait an infinite length of time.

                                      If the return value has a string length of one (LEN(i$) = 1), it means
                                      that a standard character key was pressed. The return string contains
                                      the character. An ASC() value between 1 and 31 indicates a control
                                      code.

                                      If the return value has a string length of two (LEN(i$) = 2), it means
                                      that an extended key was pressed. In this case, the first character
                                      in the result string has an ASC() value of zero (0), and the second is
                                      the extended keyboard scan code. For example, pressing the F1 key
                                      will return CHR$(0, 59).

                                      If the return value has a string length of four (LEN(i$) = 4), it
                                      means that a mouse event has occurred while mouse trapping was enabled.
                                      In this case, the first two characters in the string have an ASC()
                                      value of 255. The third character is an event code, while the fourth
                                      is a button code:

                                      Value Event Code Value Button Code
                                      ----- ---------- ----- -----------
                                      1 movement 0 no button
                                      2 double-click 1 left
                                      4 button press 2 right
                                      8 button release 4 second left button
                                      8 third left button
                                      16 fourth left button

                                      For example, moving the mouse with the left button pressed will return
                                      CHR$(255, 255, 1, 1). Button presses can be combined. For example,
                                      pressing the left and right mouse buttons together will return
                                      CHR$(255, 255, 4, 3). The Mouse must be enabled with the MOUSE
                                      statement in order to receive mouse events.

                                      Comment


                                      • #20
                                        Graphic waitkey$

                                        GRAPHIC WAITKEY$
                                        ----------------
                                        Purpose
                                        Reads a keyboard character or extended key, waiting until one is ready.

                                        Syntax
                                        GRAPHIC WAITKEY$ [To WaitVar$]
                                        GRAPHIC WAITKEY$ ([KeyMask$] [,TimeOut&]) [TO WaitVar$]

                                        Function Form
                                        WaitVar$ = GRAPHIC$ (WAITKEY$)
                                        WaitVar$ = GRAPHIC$ (WAITKEY$, [KeyMask$] [,TimeOut&])

                                        Remarks
                                        Reads a character or extended key from the keyboard without echoing
                                        anything to the screen. If no data is available, GRAPHIC WAITKEY$
                                        will wait for an event to occur. It is very similar to GRAPHIC INKEY$,
                                        except that it waits for input to be available. While waiting, time
                                        slices are released to the operating system to reduce CPU load.

                                        It returns a string of one or two characters if a key was pressed.
                                        If the TO clause is omitted, the keyboard character is discarded.

                                        If the optional KeyMask$ expression is included, only a limited set
                                        of keys are recognized. KeyMask$ may include any number of Sub-Masks,
                                        one for each key to observe. For example, GRAPHIC WAITKEY$("YyNn")
                                        will recognize upper-case or lower-case Y or N (for yes/no answers),
                                        while any other key will be ignored. If KeyMask$ is omitted, or
                                        evaluates to a zero-length string, any key event will be recognized.

                                        If the optional TimeOut& expression is included, it tells the maximum
                                        number of milliseconds to wait for a key. GRAPHIC WAITKEY$(5000) will
                                        wait a maximum of 5 seconds. The specified TimeOut period will only
                                        be approximate, so you should not rely upon precision accuracy. If
                                        the TimeOut period is exceeded, a zero-length string is returned. If
                                        the TimeOut& parameter is omitted, or evaluates to zero (0), it will
                                        wait an infinite length of time.

                                        A string length of one (LEN(i$) = 1) means that a standard character
                                        key was pressed. The result string contains the character. An ASC()
                                        value between 1 and 31 indicates a control code.

                                        A string length of two (LEN(i$) = 2) means that an extended key was
                                        pressed. In this case, the first character in the result string has
                                        an ASC() value of zero (0), and the second is the extended keyboard
                                        scan code. For example, pressing the F1 key will return CHR$(0, 59).

                                        Comment

                                        Working...
                                        X