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.

This post describes two more routines from my Action! windowing library.  These functions are for printing to a window and clearing a windows contents.  The functions are part of the file LIBWIN.ACT.  The entire library will be released at conclusion of the blog posts.  The routines are:

• WPrint – Print to a window
• WClr – Clear a windows contents

Print (WPrint)

This routine is used to print text at coordinates within a given window.  It takes 4 parameters:

• Window handle (n)
• X position / column (x)
• Y position / row (y)
• String to print (s)

If no errors are encountered it returns 0 (good).  If an error does occur, it returns the error code.

The print routine works as follows.

• First a default return code of error status NOT OPEN is set.
• Next the address of the window handle is computed.  Then the status of the windows handle is checked.
• If the windows status is free, the routine exits with the default error code previously set.
• If the windows status is used, the passed string is copied to a temporary buffer.  I check is made to ensure the length won’t exceed the windows right boundary.  If it will, its truncated.  Next the string is converted to internal character code from ATASCII because it will be copied directly to screen memory.  Then if the inverse flag is set, the string is inversed.
• The screen position in memory is then computed.  If the x parameter was specified as WPCENT, the text will be centered, otherwise it will be placed at the x position specified.  The temporary string is then copied directly into screen memory.
• The return code is set to 0 (good) and the routine exits.

; --------------------------------------
; Func..: BYTE WPrint(BYTE n,x,y
;                     CARD POINTER s)
; Desc..: Print text in window at pos
; Params: n = number of window handle
;         x = column to print at
;         y = row to print at
;         s = Text string pointer
; Notes.: Max 38 for frame
; Return: 0 if success
;         >100 on error
; --------------------------------------
BYTE FUNC WPrint(BYTE bN,x,y CHAR POINTER pS)
  BYTE bR
  CHAR ARRAY cL(38)
  CARD POINTER cS

  ; Set default return code
  bR=WERNOPN

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

  ; Only if handle in use
  if pWn.bS#WSFREE then
    ; Copy string to line buffer
    SCopy(cL,pS)

    ; Ensure text wont overrun
    ; Check len not > width-x-1
    ; x is column offset
    ; width inc frames, remove 1
    ; instead of 2 due to x as 1 based
    if cL(0) > pWn.bW-x-1 then
      cL(0)=pWn.bW-x-1
    fi

    ; Convert from ATA to INT
    StrAI(cL)

    ; Make inverse if ON
    if pWn.bI=WINVON then
      ; Always inverse title text
      ; Skip first byte (str len)
      StrInv(cL+1,cL(0))
    fi

    ; Find top left corner of window
    ; in screen memory (inside frame)
    cS=RSCRN+(pWn.bY*40)+pWn.bX

    ; Add 40 for each row (Y)
    cS==+(y*40)

    ; If not center, move to pos
    if x#WPCENT then
      ; Add x for column
      cS==+x
    ; Else move to centered position
    else
      ; Add width-length/2 for centered x.
      cS==+((pWn.bW-cL(0))/2)
    fi

    ; Move it to screen, skip len byte
    MoveBlock(cS,cL+1,cL(0))

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

Clear (WClr)

This routine is used to clear the inner contents of the given window.  It takes only one parameter which is the window handle number to clear.  It returns 0 (good) if no errors were encountered, otherwise it returns the error code.  The routine works in the following way:

• First, a default error return code of NOT OPEN is set.
• Next, the address of the window handle is computed.  The handle status is then checked.
• If the window status is free, the routine exits passing back the previously defined error code of NOT OPEN.
• If the window status is used, the top left position for the contents of the window (inside border) is computed.  An empty string is created for the windows content width (not frame width).  If the window has the inverse flag set, the empty string is inversed.
• Line by line the empty string is then copied directly into screen memory.
• Finally, the return code of 0 (good) is set and the routine exits with the return code.

; --------------------------------------
; Func..: BYTE WClr(BYTE n)
; Desc..: Clears window contents
; Params: n = number of window handle
; Return: 0 if success
;         >100 on error
; --------------------------------------
BYTE FUNC WClr(BYTE bN)
  BYTE bR,bL
  CHAR ARRAY cL(38)
  CARD POINTER cS

  ; Set default return code
  bR=WERNOPN

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

  ; Only if handle in use
  if pWn.bS=WSUSED then
    ; Find top left corner of window
    ; in screen memory (inside frame)
    cS=RSCRN+(pWn.bY*40)+pWn.bX+41

    ; Make line empty
    SetBlock(cL,pWn.bW-2,0)

    ; If inverse flip line
    if pWn.bI=WINVON then
      StrInv(cL,pWn.bW-2)
    fi

    ; Clear window line by line
    for bL=1 to pWn.bH-2
    DO
      ; Restore underlying scrn from win mem
      MoveBlock(cS,cL,pWn.bW-2)
      ; Inc scr by 40 to next line start
      cS==+40
    OD

    ; Set return
    bR=0
  fi
RETURN(bR)

Usage

To demonstrate these functions, I’ve added on to the same demonstration program used in previous posts.  A couple of minor changes were made to the window sizes to make them taller so they would overlap more, purely cosmetic.

The notable additions to the program are the WPrint() lines, the WClr() line, and the addition of another keystroke wait.  This also demonstrates the usage of centering with WPrint().  The second “Hello” in window 3 is centered, as is “Inverse ATASCII Podcast” in window 2.

; 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)

; 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

Running the program produces the following screens.  The first shows the windows opened, with content applied.  It is waiting for a keystroke before proceeding:

This shows the windows after the contents of window 3 have been cleared.  It is again waiting for a keystroke before continuing:

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

The next post will include functions for positioning the virtual cursor, and for putting single characters to a window.

In this post I show how the windowing system close routine works,  as well as introduce a window titling routine.  All of the routines presented here are part of the window library LIBWIN.ACT.

Close (WClose)

The close routine takes one parameter when called – the window handle to close.  Windows can be closed out of sequence, but new windows should not be opened until all the topmost windows have been closed.  If you do want to close and open a new window in the middle of the stack, the window size of the new window MUST be identical to prevent overwriting another windows screen buffer memory.

The close routine works in the following manner:

• First it sets the default return code to an error code of NOT OPEN.  This assumes the window handle specified is not currently open.
• It then computes the location of the windows handle within the window handle memory.
• Then, if the windows handle status is free, the routine exits passing back the default error code NOT OPEN.
• If the windows handle status is not free, it computes the location of the top left corner of the window in screen memory, then restores the screen contents the window was covering one line at a time from top to bottom by copying the saved screen contents from the windows screen buffer memory.  Then the windows screen buffer memory is cleared and the pointer to the next free space is moved to  the start of this windows screen buffer memory.  Last, the window handles attributes are reset, the return code of 0 (good) is set and the routine exits.

; --------------------------------------
; Func..: BYTE WClose(BYTE n)
; Desc..: Closes a window
; Params: n = number of window handle
; Return: 0 if success
;         >100 on error
; --------------------------------------
BYTE FUNC WClose(BYTE bN)
  BYTE bR,bL
  CARD POINTER cS,pM

  ; Set default return code
  bR=WERNOPN

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

  ; Only if handle in use
  if pWn.bS#WSFREE then
    ; Find top left corner of window
    ; in screen memory
    cS=RSCRN+(pWn.bY*40)+pWn.bX

    ; Set temp ptr to start of win mem
    pM=pWn.cM

    ; Restore screen line by line
    for bL=0 to pWn.bH-1
    DO
      ; Restore underlying scrn from win mem
      MoveBlock(cS,pM,pWn.bW)
      ; Inc mem ptr index by width
      pM==+pWn.bW
      ; Inc scr by 40 to next line start
      cS==+40
    OD

    ; Clear window memory
    Zero(pWn.cM,pWn.cZ)

    ; Set win mem ptr to prev location
    cpWM==-pWn.cZ

    ; Clear handle
    pWn.bS=WSFREE
    pWn.bX=0
    pWn.bY=0
    pWn.bW=0
    pWn.bH=0
    pWn.bI=WINVOFF
    pWn.cM=baWM  ; point at base storage
    pWn.cZ=0

    ; Set return
    bR=0
  fi
RETURN(bR)

Title (WTitle)

The title routine sets the windows title.  It requires two parameters; the window handle, and a pointer to the string containing the title.  Titles should be at least 4 characters smaller than the window width.  If successful, it returns 0 (good).  If something went wrong, it returns an error code.

The routine works in the following manner:

• First a default error return code of NOT OPEN is assigned.  This assumes the window handle specified is not currently open.
• It then computes the location of the windows handle within the window handle memory.
• Then, if the windows handle status is free, the routine exits passing back the default error code NOT OPEN.
• If the windows handle status is used, it builds a string to present in memory which is a copy of the passed title, but includes bookends.  This string is then converted from ATASCII to internal character code because the string will be copied directly into screen memory rather than through CIO.  If the window was specified as inverse, the entire built title string is inversed including the bookends, otherwise just the title is inversed. Finally, the titles location in screen memory is computed, and the built title string is copied directly to screen memory to that location.
• Then the return code is set to 0 (good) and the routine exits.

; --------------------------------------
; Func..: BYTE WTitle(BYTE n
;                     CARD POINTER s)
; Desc..: Add title decor to window
; Params: n = number of window handle
;         s = Title string pointer
; Notes.: Max 36 for frame and bookends
; Return: 0 if success
;         >100 on error
; --------------------------------------
BYTE FUNC WTitle(BYTE bN CARD POINTER pS)
  BYTE bR
  CHAR ARRAY cL(36)
  CARD POINTER cS

  ; Set default return code
  bR=WERNOPN

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

  ; Only if handle in use
  if pWn.bS=WSUSED then
    ; Create title string
    ; Copy string
    SCopy(cL+1,pS)
    ; Set open bookend
    cL(1)=4
    ; Set close bookend
    cL(pS(0)+2)=1
    ; Set string len to include bookends
    cL(0)=pS(0)+2

    ; Convert from ATA to INT
    StrAI(cL)

    ; If inverse on, inverse all
    if pWn.bI=WINVON then
      ; Skip first 1b (str len)
      StrInv(cL+1,cL(0))
    ; Else inverse off, inverse only text
    else
      ; Skip first 2b (str len,bookend)
      ; Skip last 1b (bookend)
      StrInv(cL+2,cL(0)-2)
    fi

    ; Find top left corner +1 of window
    ; in screen memory
    cS=RSCRN+(pWn.bY*40)+pWn.bX+1

    ; Move title to screen
    MoveBlock(cS,cL+1,cL(0))

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

Usage

To demonstrate the newly introduced functions, this small program is employed.  It adds in two more files from my Action! library.  They are required to use the function WaitKC().  WaitKC waits for a keystroke or console key press.  These files are:

• DEFINES.ACT – Definitions used by my Action! library routines.
• LIBMISC.ACT – Miscellaneous functions.  Pulled in for WaitKC().

Notable changes in the demonstration program are the addition of the WTitle() lines, WClose() lines, and the WaitKC() line.

; 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,6,WINVOFF)
WTitle(bW1,"One")

; Open window 2
bW2=WOpen(5,15,30,6,WINVON)
WTitle(bW2,"TWO")

; Open window 3
bW3=WOpen(15,8,10,8,WINVOFF)
WTitle(bW3,"Three")

; 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

Running the demonstration program produces the following.  The first screen shot is after the windows have been opened with titles applied, and is waiting for a keystroke.  The wait was required due to the window system speed.  Without the wait, it would just blink. Yes, its that fast.

This screen shot shows the windows have been closed and control has returned to the Action! cartridge (top line):

The next post will include a routine to print a string to a window, and a routine to clear a windows contents.