====== UIFC ======

===== Background =====

UIFC (User InterFaCe) is the text mode full-screen user interface library used by [[util:SCFG]], [[util:echocfg]], and others.  It was originally inspired by the text mode user interface for NetWare 2.x server management utilities for DOS (e.g. [[https://www.zx.net.nz/netware/client/syscon-375/|SYSCON]]), and was written from scratch by [[person:Digital Man]].

===== Interfaces =====

==== Output ====

The UIFC library uses the Synchronet Console I/O Library (CIOLIB).

=== Windows Console Mode ===

== Windows Terminal ==

UIFC apps are often not pretty when run from within Windows Terminal (''wt.exe''). To use the legacy Windows Console Host instead, run ''conhost.exe'' and pass the path and arguments to the UIFC application on the command-line.

==== Input ====

=== Mouse ===
In most environments, UIFC applications support mouse input:
  * Left-click to select a menu option
  * Left-click outside of active window to move backwards
  * Right-click to move backwards/exit
  * Left-click ''[■]'' to move backwards/exit
  * Left-click ''[?]'' for a context-sensitive help screen
  * Left-click ''▼'' to scroll down one page
  * Left-click ''▲'' to scroll up one page

=== Keyboard ===

^ Operation           ^ Keys ^
| Move selection bar  | Up and Down arrows, Home (''^B''), End (''^E''), Page-up (''^U''), Page-down (''^D'') |
| Select item         | Enter |
| Edit item           | ''F2'' |
| Insert item         | Insert or ''+'' |
| Delete item         | Delete or ''-'' |
| Exit                | ESC or Backspace (''^H'') |
| Copy item           | ''^C'' or Ctrl-Insert or F5 |
| Cut item            | ''^X'' or Shift-Delete |
| Paste item          | ''^V'' or Shift-Insert or F6 |


===== Development Documentation =====

==== C Interface ====

=== uifc.h ===

The C API is exposed through the header file: ''uifc.h''.

=== uifc32.c ===

The 32-bit port of the DOS version, initialized using uifcini32().  This is the best supported version and is reccomended for effectively every use.

=== uifcx.c ===

The command-line version using standard I/O, initialized using uifcinix().  This version is a "last resort" type of implementation.  Many features don't work as intended and it can be difficult to navigate the menus.  it is intended to work though.


==== Javascript Interface ====

See [[http://www.synchro.net/docs/jsobjs.html#uifc|JavaScript Object Reference]]

When using uifc.list, you can pass the WIN_SAV option, along with a context object to preserve the menu selection index.

The context object is created as follows:

<code>
var ctx = new uifc.list.CTX(
  0, // current
  0, // bar
  0, // left
  0, // top
  0 // width
);
</code>

==== UIFC List Window Flags ====

^ Flag ^ Description ^
| WIN_ORG | Original menu, destroy valid screen area  | 
| WIN_SAV | Save existing text and replace when finished (use with context object) |
||
| WIN_ACT | Menu remains active after a selection |
| WIN_INSACT | Remains active after insert key | 
| WIN_DELACT | Remains active after delete key |
| WIN_CHE | Stay active after escape if changes |
| WIN_EXTKEYS | Return on any keypress. Return value is -2 - keyvalue | 
| WIN_POP | Exit the list as though ESC was pressed. For use after WIN_EXTKEYS or WIN_DYN |
| WIN_SEL | Exit the list as though ENTER was pressed. For use after WIN_EXTKEYS or WIN_DYN |
| WIN_ESC | Screen is active when escape is hit |
| WIN_EDITACT | Remain active after edit key | 
||
| WIN_L2R | Center the window based on width | 
| WIN_T2B | Center the window based on height |
| WIN_RHT | Place window against right side of screen | 
| WIN_MID | Place window in middle of screen | 
| WIN_BOT | Place window against bottom of screen | 
| WIN_FIXEDHEIGHT | Use light_height from uifc struct | 
| WIN_NOBRDR | Do not draw a border around the window | 
|||
| WIN_IMM | Draw window and return immediately | 
| WIN_INACT | Draw window inactive, intended for use with WIN_IMM |
|||
| WIN_DYN | Dynamic window, return at least every second | 
| WIN_REDRAW | Force redraw on dynamic window | 
| WIN_NODRAW | Force not to redraw on dynamic window | 
|||
| WIN_INS | Allow user to use insert key | 
| WIN_DEL | Allows use to use delete key | 
| WIN_COPY | Allows F5 to Get/Copy a menu item | 
| WIN_PASTE | Allows F6 to Put/Paste a menu item |
| WIN_XTR | Add extra line at end for inserting at end |
| WIN_CUT | Allow Ctrl-X/Cut a Menu Item | 
| WIN_EDIT | Allow F2 to edit a menu item | 
| WIN_PASTEXTR | Allow paste into extra (blank) item |  
|||
| WIN_HLP | Parse Help Codes |
| WIN_PACK | Pack text in window (no padding) | 
| WIN_FAT | Do not pad outside borders | 
| WIN_UNGETMOUSE | If the mouse is clicked outside window, put mouse even back into even queue | 


==== UIFC Input Keyboard Modes ====
^ Flag ^ Description ^
| K_NONE | No special behavior | 
| K_UPPER | Converts all letters to upper case | 
| K_UPRLWR | Upper/lower case automatically |
| K_NUMBER | Allow numbers only | 
| K_MSG | Allows Ctrl-A codes | 
| K_EDIT | Edit string passed | 
| K_ALPHA | Only allow alphabetic characters | 
| K_SCANNING | UPC Scanner is active, return on '%' | 
| K_LEFTEXIT | Allow exit from getstr() with backspace | 
| K_TABEXIT | Exit on TAB or BACKTAB | 
| K_DECIMAL | Allow floating point numbers only |
| K_DEUCEEXIT | Return on up/down/F2 | 
| K_MOUSEEXIT | Returns when mouse is clicked outside of input area (not window) |
| K_PASSWORD | Do not display text while editing | 
| K_FIND | Don't set the "changes" flag | 

==== UIFC List Return Input Masks ====

Use these masks to check for specific inputs.

^ Mask ^ Description ^
| MSK_ON | Use when checking input (see example) |
| MSK_OFF | Use when checking input (see example) | 
| MSK_INS | Insert key pressed, or ENTER pressed on empty entry | 
| MSK_DEL | Delete key pressed | 
| MSK_COPY | Item copied (Ctrl-C) | 
| MSK_CUT | Item cut (Ctrl-X) | 
| MSK_PASTE | Item pasted (Ctrl-V) | 
| MSK_EDIT | Item was selected for edit (F2) |

Example JavaScript Usage:

<code>
if ((selection & MSK_ON) == MSK_DEL) {
    // delete key pressed
    selection &= MSK_OFF;
}
</code>

{{tag>javascript uifc}}