home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS 1992 June / SIMTEL_0692.cdr / msdos / turbo_c / popups.arc / POPUPS.DOC < prev    next >
Text File  |  1989-01-19  |  16KB  |  495 lines
  1.  
  2.     This document is very slim, but it's better than nothing.
  3.     Better docs next time.
  4.  
  5.     This package was written with TURBOC v1.5, and will work with v1.5
  6.     or v2.0.
  7.  
  8.     This package is made up of 22 function calls, offering simple calls
  9.     to handle popup windows. A large range of special parameters may be
  10.     easily handled such as exploding windows, shrinking windows, sound
  11.     effects, colors, 5 differant border styles, 9 differant shadow styles
  12.     and more. Status parameters are also easily obtained such as total and
  13.     remaing buffer space, total and remaining windows, current window id,
  14.     height, and width, as well as version number, current explode, shrink
  15.     and sound effects values.
  16.         The next release will implement the ability to pop (move) buried
  17.     windows to top screen level.
  18.  
  19.  
  20.  
  21.     Kevin Murphy (sysop)
  22.     Murphy's Remote
  23.     Los Altos, CA.
  24.     (415) 949-1072
  25.     2400/1200/300bps
  26.     24 hrs/7 days
  27.  
  28.  
  29.      ---------------------------------------------------------------------------
  30.     parameter definitions
  31.     ---------------------------------------------------------------------------
  32.  
  33.     int mode        - mode selects the text mode for the popup windows, this
  34.                       parameter is supplied only to the init_popup() function.
  35.  
  36.                       Where valid values are: (defined in conio.h)
  37.                                         BW40     (0)  = Black & White 40 by 25.
  38.                                         C40     (1)  = Color 40 by 25.
  39.                                         BW80    (2)  = Black & White 80 by 25.
  40.                                         C80     (3)  = Color 80 by 25.
  41.                                         MONO    (7)  = Monochrome 80 by 25.
  42.  
  43.     int left          - left supplies the windows left edge screen coordinate.
  44.  
  45.                       Where 1 through 79 are valid values.
  46.  
  47.     int top            - top supplies the windows top edge screen coordinate.
  48.  
  49.                       Where 1 through 24 are valid values.
  50.  
  51.     int right       - right supplies the windows right edge screen coordinate.
  52.  
  53.                       Where 2 through 80 are valid values.
  54.  
  55.     int bottom        - bottom is the windows bottom edge screen coordinate.
  56.  
  57.                       Where 2 through 25 are valid values.
  58.  
  59.     int foreground     - foreground supplies the windows text color attribute.
  60.  
  61.                       Where valid values are: (defined in conio.h)
  62.                                                 BLACK            (0)
  63.                                                 BLUE            (1)
  64.                                                 GREEN            (2)
  65.                                                 CYAN            (3)
  66.                                                 RED                (4)
  67.                                                 MAGENTA            (5)
  68.                                                 BROWN            (6)
  69.                                                 LIGHTGRAY        (7)
  70.                                                 DARKGRAY        (8)
  71.                                                 LIGHTBLUE        (9)
  72.                                                 LIGHTGREEN        (10)
  73.                                                 LIGHTCYAN        (11)
  74.                                                 LIGHTRED        (12)
  75.                                                 LIGHTMAGENTA    (13)
  76.                                                 YELLOW            (14)
  77.                                                 WHITE            (15)
  78.  
  79.                                             Also BLINK             (128)
  80.                                             may be added to the color.
  81. >>>
  82.  
  83.     int background     - background supplies the background color attribute.
  84.  
  85.                       Where valid values are: (defined in conio.h)
  86.                                                 BLACK            (0)
  87.                                                 BLUE            (1)
  88.                                                 GREEN            (2)
  89.                                                 CYAN            (3)
  90.                                                 RED                (4)
  91.                                                 MAGENTA            (5)
  92.                                                 BROWN            (6)
  93.                                                 LIGHTGRAY        (7)
  94.  
  95.     int border        - border supplies the windows border color attribute.
  96.  
  97.                       Valid values are the same as 'foreground'.
  98.  
  99.     int bordertype    - bordertype supplies the windows border style.
  100.  
  101.                       Where valid values are: (defined in popups.h)
  102.                                                 NO_BORDER    (0)
  103.                                                 ONE_LINE     (1)
  104.                                                 TWO_LINE     (2)
  105.                                                 THIN_SOLID   (3)
  106.                                                 THICK_SOLID  (4)
  107.  
  108.             NO_BORDER        no border
  109.             ONE_LINE        single line box border, i.e. ─────
  110.             TWO_LINE        double line box border, i.e. ═════
  111.             THIN_SOLID      thin solid box border, i.e. ▀▀▀▀▀
  112.             THICK_SOLID     thick solid box border, i.e. █████
  113.  
  114.  
  115.     int shadow_style - shadow_style defines the shadow type, and position.
  116.  
  117.                       Where valid values are: (defined in popups.h)
  118.                                                 NO_SHADOW     (0)
  119.                                                 TL_THIN     (1)
  120.                                                 TR_THIN     (2)
  121.                                                 BL_THIN     (3)
  122.                                                 BR_THIN     (4)
  123.                                                 TL_THICK    (6)
  124.                                                 TR_THICK    (7)
  125.                                                 BL_THICK    (8)
  126.                                                 BR_THICK    (9)
  127.  
  128.  
  129.             NO_SHADOW   no shadow
  130.             TL_THIN     thin shadow behind top and left edge
  131.             TR_THIN     thin shadow behind top and right edge
  132.             BL_THIN     thin shadow behind bottom and left edge
  133.             BR_THIN     thin shadow behind bottom and right edge
  134.             TL_THICK    thick shadow behind top and left edge
  135.             TR_THICK    thick shadow behind top and right edge
  136.             BL_THICK    thick shadow behind bottom and left edge
  137.             BR_THICK    thick shadow behind bottom and right edge
  138. >>>>
  139.     ---------------------------------------------------------------------------
  140.     init_popup
  141.     ---------------------------------------------------------------------------
  142.  
  143.     Name    init_popup - save screen image, initialize popups variables,
  144.             and create the initial main screen.
  145.  
  146.     Usage    init_popup(mode,left,top,right,bottom,foreground,background,
  147.                        border,bordertype);
  148.  
  149.     Description:
  150.             Initializes all pointers and variables, save original screen
  151.             image in ram allowing for restoration of image at exit. Creates
  152.             the main screen (window 0).
  153.  
  154.     return  [int] 0 (zero) if no errors encountered, else a -1 (ERROR) is
  155.             returned if init_popup() have been called previously, and not
  156.             been properly exited via uninit_popup() or abandon_popup().
  157.  
  158.  
  159.  
  160.     ---------------------------------------------------------------------------
  161.     next_popup
  162.     ---------------------------------------------------------------------------
  163.  
  164.     Name    next_popup - create a new window.
  165.  
  166.     Usage    next_popup(mode,left,top,right,bottom,foreground,background,
  167.                        border,bordertype);
  168.  
  169.     Description:
  170.             Opens/creates a new window based on the supplied parameters and
  171.             current state of switches.
  172.  
  173.     return  [int] windows id number, or -1 (ERROR) if window request would
  174.             exceed the maximum number of windows, or if windows memory
  175.             requirements exceed the remaining buffer space.
  176.  
  177.  
  178.  
  179.     ---------------------------------------------------------------------------
  180.     previous_popup
  181.     ---------------------------------------------------------------------------
  182.  
  183.     Name    previous_popup - close current window and restore screen.
  184.  
  185.     Usage    previous_popup()
  186.  
  187.     Description:
  188.             Closes current window, restores screen image, and releases the
  189.             respective buffer space.
  190.  
  191.     return  [int] windows id number, or -1 (ERROR) if current window id is
  192.             0 (zero), i.e. there is no window to close.
  193. >>>>
  194.     ---------------------------------------------------------------------------
  195.     uninit_popup
  196.     ---------------------------------------------------------------------------
  197.  
  198.     Name    uninit_popup - restore original screen image, and mode.
  199.  
  200.     Usage    uninit_popup();
  201.  
  202.     Description:
  203.             Restore original screen image and mode, but only if current window
  204.             id is 0 (zero).
  205.  
  206.     Return     [int] -1 (ERROR) is returned if current window id is not 0 (zero)
  207.             or init_popup() has not been previously called.
  208.  
  209.  
  210.  
  211.     ---------------------------------------------------------------------------
  212.     abandon_popup
  213.     ---------------------------------------------------------------------------
  214.  
  215.     Name    abandon_popup - restore original screen image, and mode.
  216.  
  217.     Usage    abandon_popup();
  218.  
  219.     Description:
  220.             Restore original screen image and mode, regardless of the current
  221.             window id value/level.
  222.  
  223.     Return     [int] -1 (ERROR) is returned if init_popup() has not been called.
  224.  
  225.  
  226.  
  227.     ---------------------------------------------------------------------------
  228.     version_pop
  229.     ---------------------------------------------------------------------------
  230.  
  231.     Name    version_pop - returns the version number of 'popups'.
  232.  
  233.     Usage    version_pop();
  234.  
  235.     Description:
  236.             Returns the version number of 'popups'.
  237.  
  238.     Return     [int] whole version number, i.e. 101 represents version 1.01.
  239. >>>
  240.     ---------------------------------------------------------------------------
  241.     explode
  242.     ---------------------------------------------------------------------------
  243.  
  244.     Name    explode - toggles exploding window parameter switch.
  245.  
  246.     Usage    explode(toggle);
  247.                 Where 'toggle' is ON (1), or OFF (0).
  248.  
  249.     Description:
  250.             Toggles exploding window parameter switch. If switch is ON the
  251.             windows first appear very small, and then explode (expand) at
  252.             an incremental rate. If the switch is OFF, the windows appear
  253.             on the screen full size instantly.
  254.  
  255.     Return     none
  256.  
  257.  
  258.  
  259.     ---------------------------------------------------------------------------
  260.     explode_delay
  261.     ---------------------------------------------------------------------------
  262.  
  263.     Name    explode_delay - sets or returns the delay for exploding windows.
  264.  
  265.     Usage    explode_delay(unsigned int ex_delay);
  266.                 Where 'ex_delay' is a value between 0 and 1024.
  267.  
  268.     Description:
  269.             Sets or returns the incremental exploding window step delay in
  270.             milliseconds. A value of 0 (zero) will return the current delay
  271.             value. Any value higher than 0 (zero) will be accepted as the new
  272.             delay value.
  273.  
  274.     Return     [unsigned int] current value if entery value was 0 (zero).
  275. >>>>
  276.     ---------------------------------------------------------------------------
  277.     shrink
  278.     ---------------------------------------------------------------------------
  279.  
  280.     Name    shrink - toggles the shrinking window parameter switch.
  281.  
  282.     Usage    shrink(toggle);
  283.                 Where 'toggle' is ON (1), or OFF (0).
  284.  
  285.     Description:
  286.             Toggles shrinking window parameter switch. If switch is ON the
  287.             windows disappear (implode) from the screen at an incremental rate.
  288.             If the switch is OFF, the windows disappear instantly.
  289.  
  290.     Return     none
  291.  
  292.  
  293.     ---------------------------------------------------------------------------
  294.     shrink_delay
  295.     ---------------------------------------------------------------------------
  296.  
  297.     Name    shrink_delay - sets or returns the delay for shrinking windows.
  298.  
  299.     Usage    shrink_delay(unsigned int sh_delay);
  300.                 Where 'sh_delay' is a value between 0 and 1024.
  301.  
  302.     Description:
  303.             Sets or returns the incremental shrinking window step delay in
  304.             milliseconds. A value of 0 (zero) will return the current delay
  305.             value. Any value higher than 0 (zero) will be accepted as the new
  306.             delay value.
  307.  
  308.     Return     [unsigned int] current value if entery value was 0 (zero).
  309. >>>>
  310.     ---------------------------------------------------------------------------
  311.     noise
  312.     ---------------------------------------------------------------------------
  313.  
  314.     Name    noise - toggles the window sound effects switch.
  315.  
  316.     Usage    noise(toggle);
  317.                 Where 'toggle' is ON (1), or OFF (0).
  318.  
  319.     Description:
  320.             Toggles the window sound effects switch. If switch is ON the
  321.             windows are accompanied by sound. If the switch is OFF, no
  322.             sound is made.
  323.  
  324.     Return     none
  325.  
  326.  
  327.  
  328.     ---------------------------------------------------------------------------
  329.     noise_tone
  330.     ---------------------------------------------------------------------------
  331.  
  332.     Name    noise_tone - sets or returns the base sound effects frequency.
  333.  
  334.     Usage    noise_tone(unsigned int tone);
  335.                 Where 'tone' is a value between 0x0000 and 0xffff.
  336.  
  337.     Description:
  338.             Sets or returns the base sound effects frequency in Hz (Hertz).
  339.             (Hertz = cycles per second). The window sound effects will
  340.             reload this base value each time a window is opened or closed
  341.             if the sound effects are enabled.
  342.             > Also see noise_step().
  343.  
  344.     Return     [unsigned int] current value if entery value was 0 (zero).
  345.  
  346.  
  347.  
  348.     ---------------------------------------------------------------------------
  349.     noise_step
  350.     ---------------------------------------------------------------------------
  351.  
  352.     Name    noise_step - sets or returns the sound effects frequency step.
  353.  
  354.     Usage    noise_step(unsigned int tone);
  355.                 Where 'tone' is a value between 0x0000 and 0xffff.
  356.  
  357.     Description:
  358.             Sets or returns the sound effects frequency step in Hz (Hertz).
  359.             (Hertz = cycles per second). When the windows are in the shrinking
  360.             or exploding mode, the sound effects frequency is increased by
  361.             this value at the begining and end of each incremental size step.
  362.  
  363.     Return     [unsigned int] current value if entery value was 0 (zero).
  364. >>>>
  365.     ---------------------------------------------------------------------------
  366.     pop_max
  367.     ---------------------------------------------------------------------------
  368.  
  369.     Name    pop_max - returns the maximum number of windows allowed.
  370.  
  371.     Usage    pop_max();
  372.  
  373.     Description:
  374.             Returns the maximum number of windows allowed, (controlled by
  375.             a constant value in source file).
  376.  
  377.     Return     [int] maximum windows.
  378.  
  379.  
  380.     ---------------------------------------------------------------------------
  381.     pop_left
  382.     ---------------------------------------------------------------------------
  383.  
  384.     Name    pop_left - returns the remaining number of windows allowed.
  385.  
  386.     Usage    pop_left();
  387.  
  388.     Description:
  389.             Returns the remaining number of availible windows before exceeding
  390.             maximum allowed.
  391.  
  392.     Return     [int] remaing windows.
  393.  
  394.  
  395.     ---------------------------------------------------------------------------
  396.     buf_max
  397.     ---------------------------------------------------------------------------
  398.  
  399.     Name    buf_max - returns the size of the windows memory buffer.
  400.  
  401.     Usage    buf_max();
  402.  
  403.     Description:
  404.             Returns the size of the windows memory buffer in bytes, (defined
  405.             by a constant value in source file).
  406.  
  407.     Return     [int] number of bytes in buffer.
  408.  
  409.  
  410.     ---------------------------------------------------------------------------
  411.     buf_left
  412.     ---------------------------------------------------------------------------
  413.  
  414.     Name    buf_left - returns the remaining number of bytes in buffer.
  415.  
  416.     Usage    buf_left();
  417.  
  418.     Description:
  419.             Returns the remaining number of availible bytes in windows memory
  420.             buffer.
  421.  
  422.     Return     [int] remaing bytes in buffer.
  423. >>>
  424.     ---------------------------------------------------------------------------
  425.     high_popup
  426.     ---------------------------------------------------------------------------
  427.  
  428.     Name    high_popup - returns the usable height of window.
  429.  
  430.     Usage    high_popup();
  431.  
  432.     Description:
  433.             Returns the usable height of current window in number of rows.
  434.  
  435.     Return     [int] number of rows.
  436.  
  437.  
  438.     ---------------------------------------------------------------------------
  439.     wide_popup
  440.     ---------------------------------------------------------------------------
  441.  
  442.     Name    wide_popup - returns the usable width of window.
  443.  
  444.     Usage    wide_popup();
  445.  
  446.     Description:
  447.             Returns the usable width of current window in number of columns.
  448.  
  449.     Return     [int] number of columns.
  450.  
  451.  
  452.     ---------------------------------------------------------------------------
  453.     id_popup
  454.     ---------------------------------------------------------------------------
  455.  
  456.     Name    id_popup - returns the current windows id number.
  457.  
  458.     Usage    id_popup();
  459.  
  460.     Description:
  461.             Returns the usable current windows id number.
  462.  
  463.     Return     [int] window id number.
  464. >>>
  465.     ---------------------------------------------------------------------------
  466.     shadow_color
  467.     ---------------------------------------------------------------------------
  468.  
  469.     Name    shadow_color - sets the color attribute of the windows shadow.
  470.  
  471.     Usage    shadow_color(int foreground);
  472.  
  473.     Description:
  474.             Sets the color attribute of the windows shadow.
  475.             > Also see shadow().
  476.  
  477.     Return     none
  478.  
  479.  
  480.     ---------------------------------------------------------------------------
  481.     shadow
  482.     ---------------------------------------------------------------------------
  483.  
  484.     Name    shadow - sets the style (if any) of the windows shadow.
  485.  
  486.     Usage    shadow(int shadow_style);
  487.  
  488.     Description:
  489.             Sets the style of the windows shadow.
  490.  
  491.     Return     none
  492.  
  493.  
  494.  
  495.