Unfinished Bitness

This is about the first widget for my Action! windowing library. To separate a widgets function name from a window function, I used a G. So I’m calling them gadgets instead. This gadget is a progress bar.

Progress Bar (GProg)

The progress bar indicator displays only the actual progress bar at the coordinates within the window specified.  This gives the freedom to include other elements in the progress window as desired.  Each call to the function displays a bar for the percentage given.  It is possible to go backwards as well (i.e.: 100 to 0 instead of 0 to 100).

The function GProg takes four parameters.  They are:

• Window handle number (bN)
• X position / column (x) – within the windows bounds
• Y position / row (y) – within the windows bounds
• Bar size – percentage complete (0 to 100, whole numbers only)

There is no return value, and as such the function is declared as a PROCedure.

The procedure works as follows:

• First, and empty string is created.
• Next the string is filled from left to right with inverse spaces.  The number of spaces is calculated by taking the bar size parameter and dividing it by 5.  Why 5?  The bar is 20 characters long.  20 * 5 is 100.
• Last the bar is printed to the window using WPrint, which writes directly to screen memory in the appropriate location.

; --------------------------------------
; Proc..: GProg(BYTE bN,x,y,bS)
; Desc..: Displays progress bar
; Params: bN =  number of window handle
;         x = column for cursor
;         y = row for cursor
;         bS = bar size (pct complete)
; --------------------------------------
PROC GProg(BYTE bN,x,y,bS)
  INT i
  CHAR ARRAY cL(21),cB(21)

  ; Set default and block lines
  SCopy(cL,"                    ")

  ; Update bar contents
  ; Div by 5 since bar is 1/5 100
  for i=1 to bS/5
  DO
    cL(i)=CINVSP
  OD

  ; Display new bar
  WPrint(bN,x,y,cL)
RETURN

Usage

To demonstrate this gadget I created a new program. This one opens a window on the left to display each window handles status. A progress bar is displayed while each status is being gathered and printed.

; Program: WINDOW.ACT
; Author.: Wade Ripkowski
; Date...: 2016.04
; Desc...: Test Windowing Library
; License: Creative Commons
;          Attribution-NonCommercial-
;          NoDerivatives
;          4.0 International

; Include library
INCLUDE "D3:DEFINES.ACT"
INCLUDE "D3:DEFWIN.ACT"
INCLUDE "D3:LIBSTR.ACT"
INCLUDE "D3:LIBWIN.ACT"
INCLUDE "D3:LIBMISC.ACT"
INCLUDE "D3:LIBGADG.ACT"

; Start
MODULE

PROC Main()
; Window handles
BYTE bW1,bW2,bLp,bS
INT iP

; Init Window System
WInit()

; Open window 1
bW1=WOpen(9,2,20,14,WINVOFF)
WTitle(bW1,"Status")
WPrint(bW1,1,1,"Window Status")
WPrint(bW1,1,2,"------ ------")

; Open progress bar window
bW2=WOpen(7,18,24,4,WINVOFF)
WPrint(bW2,2,1,"Progress:")

; Display initial progress bar
GProg(bW2,2,2,0)

; Loop through each window handle
for bLp=0 to 9
DO
    ; Get the status
    bS=WStat(bLp)

    ; Print the window handle #
    WPos(bW1,6,3+bLp)
    WPut(bW1,bLp+48)

    ; Print the handle status
    if bS=WSUSED then
        WPrint(bW1,8,3+bLp,"Used")
    else
        WPrint(bW1,8,3+bLp,"Free")
    fi

    ; Update progress bar
    iP=((bLp+1) MOD 10)*10
    if iP=0 then
        iP=100
    fi
    GProg(bW2,2,2,iP)

    ; Wait for a keystroke or console key
    WaitKC()
OD

; Close window 2
WClose(bW2)

; Close window 1
WClose(bW1)

RETURN

Results

When the program is run, it expects a keypress after each status line is printed.  Screenshots of the demonstration program.  The first is at the first of 10 window handles (or 10 percent):

The next is after the fifth window handle has been displayed (or 50 percent):

The last is after all 10 window handles status have been displayed (or 100 percent):

The next post will be the release of the entire library to date.

This post introduces a function to check the status of a window handle: WStat().  It is also part of my Action! library window file LIBWIN.ACT.

Status (WStat)

The status routine simply returns the window handles status.  It will be either WSFREE (not in use), or WSUSED (used).  It requires one parameter which is the window handle number to check.
The function works in the following manner:

• It computes the window handles memory location.
• It then returns the window handles status byte value.

; --------------------------------------
; Func..: BYTE WStat(BYTE n)
; Desc..: Tests if window handle is open
; Params: n = number of window handle
; Return: WSUSED (in use) or
;         WSFREE (not used)
; --------------------------------------
BYTE FUNC WStat(BYTE bN)
  ; Find window handle record
  pWn=baW+(WRECSZ*bN)
RETURN(pWn.bS)

Usage

The demonstration program has once again been expanded.  This time a fourth window is opened.  It it, the status of the first 5 windows is displayed.  Notable differences are in the section commented for window 4:

; Program: WINDOW.ACT
; Author.: Wade Ripkowski
; Date...: 2016.04
; Desc...: Test Windowing Library
; License: Creative Commons
;          Attribution-NonCommercial-
;          NoDerivatives
;          4.0 International

; Include library
INCLUDE "D3:DEFINES.ACT"
INCLUDE "D3:DEFWIN.ACT"
INCLUDE "D3:LIBSTR.ACT"
INCLUDE "D3:LIBWIN.ACT"
INCLUDE "D3:LIBMISC.ACT"

; Start
MODULE

PROC Main()
; Window handles
BYTE bW1,bW2,bW3,bW4,bLp,bS

; Init Window System
WInit()

; Open window 1
bW1=WOpen(10,5,20,7,WINVOFF)
WTitle(bW1,"One")
WPrint(bW1,1,1,"Row 1 Column 1")
WPrint(bW1,1,5,"Unfinished Bitness")

; Open window 2
bW2=WOpen(5,15,30,6,WINVON)
WTitle(bW2,"TWO")
WPrint(bW2,2,2,"2,2")
WPrint(bW2,WPCENT,4,"Inverse ATASCII Podcast")

; Open window 3
bW3=WOpen(15,8,10,10,WINVOFF)
WTitle(bW3,"Three")
WPrint(bW3,1,3,"Hello")
WPrint(bW3,3,5,"Hello")
WPrint(bW3,1,7,"Hello")

; Wait for a keystroke or console key
WaitKC()

; Clear window 3
WClr(bW3)

; Draw \ in window 3
WPos(bW3,1,1)
WPut(bW3,42)
WPos(bW3,2,2)
WPut(bW3,42)
WPos(bW3,3,3)
WPut(bW3,42)
WPos(bW3,4,4)
WPut(bW3,42)
WPos(bW3,5,5)
WPut(bW3,42)

; Open window 4
bW4=WOpen(3,3,15,9,WINVOFF)
WTitle(bW4,"4-Status")
WPrint(bW4,1,1,"Window Status")
WPrint(bW4,1,2,"------ ------")

; Loop through the first 5 window handles
for bLp=0 to 4
DO
    ; Get the status
    bS=WStat(bLp)

    ; Print the window handle #
    WPos(bW4,6,3+bLp)
    WPut(bW4,bLp+48)

    ; Print the handle status
    if bS=WSUSED then
        WPrint(bW4,8,3+bLp,"Used")
    else
        WPrint(bW4,8,3+bLp,"Free")
    fi
OD

; Wait for a keystroke or console key
WaitKC()

; Close window 4
WClose(bW4)

; Close window 3
WClose(bW3)

; Close window 2
WClose(bW2)

; Close window 1
WClose(bW1)

RETURN

Results

When the program is run it produces the following results.  All but the last screen shot are omitted as they have been covered before.  The important output (for this post) is what appears in window 4:

That concludes the Action! window library routines.  The next post will feature the first gadget, a progress indicator.

In this post I show how the virtual cursor is used and a routine to put single characters in a window. The functions introduced here are part of LIBWIN.ACT.   The contents of my library, as well as an API reference,  will be released in its entirety at the conclusion of the posts.  The functions for this post are position (WPos) and put (WPut).

Position (WPos)

The WPos function is used to position the virtual cursor.  It requires three parameters:

• Window handle number (n) – This also accepts WPABS which directs the position function to move the virtual cursor to an absolute screen position rather than a window based position.
• X position / column (x) – the column within the given window
• Y position / row (y) – the row within the given window

WPos returns either 0 (good) or an error code.

The functions works as follows:

• First, a default return code of 0 (good) is set.
• Next the window handle is checked to see if it is WPABS.  If it is, the virtual cursor position is set to the x and y coordinates specified, which are absolute screen coordinates, not window coordinates.
• If the window handle is not set as WPABS, the window handles memory location is computed.  The window handles status is then checked.
• If the window handle status is free, the routine sets the return code to the error code NOT OPEN and exits.
• If the window handle status is uses, the virtual cursors x and y positions are set relative the the windows frame coordinates.  The routine then exits.

; --------------------------------------
; Func..: BYTE WPos(BYTE n,x,y)
; Desc..: Moves cursor to x,y in window
;         or x,y of screen
; Params: n = number of window handle
;             or WPABS for screen
;         x = column for cursor
;         y = row for cursor
; Return: WERNOPN (not open) or
;         0 (good)
; --------------------------------------
BYTE FUNC WPos(BYTE bN,x,y)
  BYTE bR

  ; Set valid return
  bR=0

  ; If absolute mode
  if bN=WPABS then
    ; Set screen coords
    vCur.vX=x
    vCur.vY=y
  else
    ; Find window handle record
    pWn=baW+(WRECSZ*bN)

    ; Only if handle in use
    if pWn.bS#WSFREE then
      ; Set relative to window
      vCur.vX=pWn.bX+x
      vCur.vY=pWn.bY+y
    else
      ; Set not open return code
      bR=WERNOPN
    fi
  fi
RETURN(bR)

Put (WPut)

The WPut function puts a single character at the windowing systems virtual cursor position.  The function requires two parameters:

• Window handle number (n)
• Character value to print (x) – This should be an ATASCII code. It will be converted to internal code.

The routine will return 0 (good) if successful, otherwise an error code.

The function works in the following manner:

• First, a default error return code of NOT OPEN is set.
• Next, the byte value passed is converted to a string.
• Then the window handles memory location is computed.  The window handles status is then checked.
• If the window handles status is free, the routine exits returning the previously defined error code of NOT OPEN.
• If the window handles status is not free (in use), the routine converts the string to internal code from ATASCII code.  If the windows inverse flag is set, the string is inversed.
• The screen memory location is computed, and the string (byte) is moved to that location.  The virtual cursor position is then incremented by one just like a real cursor.
• A return code of 0 (good) is set and the routine exits.

; --------------------------------------
; Func..: BYTE WPut(BYTE n,x)
; Desc..: Puts byte x in window
;         at virtual cursor coord
; Params: n = number of window handle
;         x = ATA byte to display
; Return: WERNOPEN (not open) or
;         0 (good)
; --------------------------------------
BYTE FUNC WPut(BYTE bN,x)
  BYTE bR
  CHAR ARRAY bC(2)
  CARD POINTER pS

  ; Set default return
  bR=WERNOPN

  ; Convert passed byte into string
  bc(0)=1
  bC(1)=x

  ; Find window handle record
  pWn=baW+(WRECSZ*bN)

  ; Only if handle in use
  if pWn.bS#WSFREE then
    ; Convert byte from ATA to INT
    StrAI(bC)

    ; If window is inverse, flip byte
    if pWn.bI=WINVON then
      bC(1)==!128
    fi

    ; Find screen loc based on vCur
    pS=RSCRN+(vCur.vY*40)+vCur.vX

    ; Move byte to screen
    ; pS^=bC(1)
    MoveBlock(pS,bC+1,1)

    ; Inc virtual cur by 1
    vCur.vX==+1

    ; Set return code
    bR=0
  fi
RETURN(bR)

Usage

The previously used demonstration program is expanded here to demonstrate WPos and WPut.  Notable differences are the WPos() lines and WPut() lines.  After the third window is cleared, WPos and WPut are used to draw a line of asterisks in the window.

; Program: WINDOW.ACT
; Author.: Wade Ripkowski
; Date...: 2016.04
; Desc...: Test Windowing Library
; License: Creative Commons
;          Attribution-NonCommercial-
;          NoDerivatives
;          4.0 International

; Include library
INCLUDE "D3:DEFINES.ACT"
INCLUDE "D3:DEFWIN.ACT"
INCLUDE "D3:LIBSTR.ACT"
INCLUDE "D3:LIBWIN.ACT"
INCLUDE "D3:LIBMISC.ACT"

; Start
MODULE

PROC Main()
; Window handles
BYTE bW1,bW2,bW3

; Init Window System
WInit()

; Open window 1
bW1=WOpen(10,5,20,7,WINVOFF)
WTitle(bW1,"One")
WPrint(bW1,1,1,"Row 1 Column 1")
WPrint(bW1,1,5,"Unfinished Bitness")

; Open window 2
bW2=WOpen(5,15,30,6,WINVON)
WTitle(bW2,"TWO")
WPrint(bW2,2,2,"2,2")
WPrint(bW2,WPCENT,4,"Inverse ATASCII Podcast")

; Open window 3
bW3=WOpen(15,8,10,10,WINVOFF)
WTitle(bW3,"Three")
WPrint(bW3,1,3,"Hello")
WPrint(bW3,3,5,"Hello")
WPrint(bW3,1,7,"Hello")

; Wait for a keystroke or console key
WaitKC()

; Clear window 3
WClr(bW3)

; Draw \ in window 3
WPos(bW3,1,1)
WPut(bW3,42)
WPos(bW3,2,2)
WPut(bW3,42)
WPos(bW3,3,3)
WPut(bW3,42)
WPos(bW3,4,4)
WPut(bW3,42)
WPos(bW3,5,5)
WPut(bW3,42)

; Wait for a keystroke or console key
WaitKC()

; Close window 3
WClose(bW3)

; Close window 2
WClose(bW2)

; Close window 1
WClose(bW1)

RETURN

Results

These screen shots depict the results when the program is run.  The first screenshot shows the windows open and populated, and waiting for a keystroke:

Once a key is pressed, window 3 is cleared, then WPos() and WPut() are used to draw a line using asterisks in window 3.  It is again waiting for a keystroke:

After the windows are all closed, control is returned to the Action! cartridge:

The next post will include a function for getting the status of a window handle.