/*
   --------------------------------------------------------
   Filename.....: appFrameSize.cc
   ClassName....: appFrameSize
   Version......: 5.xxxx.
   Purpose......: NonVisual object to manage the framewin
                  position with a minimum height and
                  minimum width.
   Programmer...: Rick Miller http://www.treturn.com/dbase
   Date.........: September 02, 2004.
   Notes........: See Notes below.
   Written for..: dBASE PLUS, dB2K, and VdB 7.x.
   Rev. History.: See Revisions below.
   Dependencies.: None.
   Calls........: see x_InitExterns method for API calls.
   Called by....: Any.
   Usage........: set procedure to appFrameSize.cc additive
   Example......: see How to use below.
   Sample.......: see appFrameSize.wfm.
   --------------------------------------------------------
   Notes:
   --------------------------------------------------------
      Always call the Release() method with:
         _app.frameSize.release()
         when finished with this object.
      This object automatically attaches
         itself to _app as _app.frameSize.
      Protected methods begin with "x_".
      Protected properties begin with "~".
   --------------------------------------------------------
   How to use:
   --------------------------------------------------------
      When starting an application.
         Local oRef
         oRef  =  new appFrameSize()

         // when changing the userIni property ?
         oRef.readIni()

         // use or change any properties.

      Methods used during the application.
         _app.frameSize.Center()
         _app.frameSize.FillDesktop()
         _app.frameSize.Maximize()
         _app.frameSize.Refresh()
         _app.frameSize.SetPosition()

      When ending the application.
         _app.frameSize.save()
         _app.frameSize.release()

   --------------------------------------------------------
   Properties:    Default:             Used for:
   --------------------------------------------------------
      height          ?                as read from userIni.
                                       height.
      left            ?                as read from userIni.
                                       left position.
      minHeight      300               minimum height.
      minWidth       400               minimum width.
      top             ?                as read from userIni.
                                       top position.
      userIni     _dbwinhome + id()    ini file to use.
      width           ?                as read from userIni.
      windowState     ?                as read from userIni.
                                       0/2 (Normal/Maximized).
   --------------------------------------------------------
   Methods:
   --------------------------------------------------------
      Center()
         1) call to insure valid property values.
         2) assign _app.frameWin.windowState =  0
         3) move _app.frameWin to the center of the
            screen using this.left, this.top,
            this.width, this.height.
      FillDesktop()
         1) call to insure valid property values.
         2) assign _app.frameWin.windowState =  0
         3) position _app.frameWin to the full
            size of the desktop client area.
      getAppIni()
         Note: for use with PLUS.
         1) returns the application ini filename.
      Maximize()
         1) maximize the framewin.
         2) set the windowState property to 2.
      ReadIni()
         1) reads from userIni and assigns property values.
            [Desktop]
            FrameLeft
            FrameHeight
            FrameTop
            FrameWidth
            FrameMaximized
      Refresh()
         1) assign property values using the
            current frameWin windowState and position.
         return true/false (success/fail).
      Release()
         1) release object.
         2) close this procedure file.
      Save()
         read the current frameWin position and write the
            position to the userIni file in 1 of 3 ways.
         1) when _app.frameWin.windowState = 0
            The current _app.frameWin position is
               placed into property values that
               will be a visible position.
            Write to userIni.
            [Desktop]
            FrameLeft=this.Left
            FrameHeight=this.Height
            FrameTop=this.Top
            FrameWidth=this.Width
            FrameMaximized=0
            Maximized=0
            Position=this.left this.top
                     this.Left + this.width
                     this.top + this.Height
         2) when _app.frameWin.windowState = 1
            No writing to userIni.
         3) when _app.frameWin.windowState = 2
            Write to userIni.
            [Desktop]
            FrameMaximized=2
         return true/false (success/fail).
      SetPosition([bool])
         1) when windowState = 0, or passing a true.
            1) call to insure valid property values.
            2) assign _app.frameWin.windowState =  0
            3) move _app.frameWin to this.left this.top
               this.width this.height position.
         2) when windowState = 2
            1) maximize frameWin.
   --------------------------------------------------------
   Revisions:
   --------------------------------------------------------
      March 24, 2005
         1) modified for use with non-BDE apps.
      March 21, 2005
         1) updated for dUFLP release.
         2) added getAppIni method for PLUS users.
      March 17, 2005
         1) modified x_CalcProperties method so that
            any property values saved will be
            within the viewable area of the desktop.
         2) added a parameter for SetPosition method.
         3) renamed ShowProps method to Inspect.
         4) added Maximize method.
      March 15, 2005
         1) added a file flush when calling save().
         2) added a return value to the save() method.
      February 10, 2005
         1) renamed all external functions.
      January 01, 2005
         1) verified external functions.
   */