DataWindow Class

Object
  VObject
    EventContext
      Window
        AppWindow
          ChildAppWindow
            DataWindow
              DataDialog
              OLEDataWindow

Request Example View Source

Data windows combine the properties and behavior of both child windows and dialog windows, and add data-aware behavior that enables them to interact intelligently with data servers. When connected to a data server, a data window forms a view of the server that allows for direct access and manipulation of the server's data. Unlike the other types of windows, a data window takes on different behavior depending on how it is used. It adapts itself to the demands placed on it by its owner, behaving differently depending on the circumstances: If Owner Is Data Window Acts Like ChildAppWindow Modal DialogWindow DataWindow Modal DialogWindow (if no placement is specified) or nested sub-data window (if placement is specified) DialogWindow Modal DialogWindow ShellWindow ChildAppWindow TopAppWindow Modal DialogWindow A data window can be placed on a data window in an owner-child relationship (similar to other controls like check boxes and radio buttons). When a data window is placed on another data window in this way, it is referred to as a sub-data window. Note that only a data window can own a sub-data window because it is the only window type of window that can deal with data-related events. You can create a data window as a sub-data window when the data window is created. You can optionally specify a third parameter (nResourceID), indicating that the new data window should be created as a control on a window by giving its location and size. When placed like a control, the data window hides its border decoration and behaves like a sub-data window. (If this parameter is omitted, the data window is created as a modal DialogWindow, not a sub-data window.) See DataWindow:Init() for details. Tip: Instead of newly creating a data window, you may prefer to use the Window Editor's Auto Layout feature which—at the touch of a button—automatically creates controls for every available field in a data window's associated data server(s). See "Using the Window Editor" in the IDE User Guide. A data window is connected to a server with the Use() method. When this connection is established, each control on the window is connected to a field in the data server based on matching names: a field named CustName is connected to the control named CustName. The control always reflects the current value of the data in the data server, and assigning a value to a control automatically propagates it to the server. Data windows can be associated with data servers in two ways: in a single server or dual server (master detail) relationship. The Master-Detail option allows you to link a window to two data servers in a master-detail relationship. In this case, a data window is created for the master server with a nested sub-data window for the detail server. The field list presented is taken from the Master data server. The field that you choose is used to perform a SetSelectiveRelation() to the detail server based on its controlling order. If you do not choose a field, the detail window is updated relative to the current record position in the master window. A data window can take on two different view modes: form view, which contains individual controls for the data fields and browse view, which contains a spreadsheet-like data browser. The data window can be initially displayed in either mode, and can be switched to the other mode at any time (using the DataWindow:ViewAs() method). Any data window supports both appearances, although the developer can, of course, choose not to provide a way to select one mode or the other. The two view modes provide the same set of facilities: the same data linkage facilities, the same display options, the same data manipulation methods. From the perspective of the application, a data window has the same behavior and the same data properties regardless of view mode. The standard way of using a data window is to paint its layout in the Window Editor. This produces a resource entity that specifies what controls the window has, and their locations, sizes, captions, and accelerators. It also generates a data window subclass and an Init() method that associates names and further annotation with each control. With such a predefined layout, the window is displayed very quickly and the methods of the window have enough information to act intelligently. A data window can also be created without a resource entity. In this case, the layout of controls on the window is automatically generated when the window is connected to a data server. After a layout is automatically generated, the window has exactly the same behavior that it has with a resource-based instantiation. If a data window is switched over to a new view mode, and the new mode has not been defined through a resource entity or programmatically, the data window automatically creates a layout based on the characteristics of the connected data server. The new layout picks up all information about fields and controls that is known to the other view; thus, if complex validation rules, prompts, and help have been specified for the individual controls in form view, the columns of the browse view inherit the same properties. When a control is connected to a field in a data server, a value entered into the control or assigned to the appropriate name from the program is automatically propagated to the server. Thus, after executing this statement: the CustName field in the server has the correct value. Values are propagated up from the data server to the data window when the server repositions itself, or when another window makes a change. This requires no special action: after executing a Skip() method or assigning a value to a field, every window connected to the server is automatically updated to reflect the change. Data entered by the user is automatically validated using the rules of the field specification attached to a control or column. (For more detail on the validation rules provided, see the FieldSpec class.) If data fails the validation test, the data window will not propagate invalid information down to the server or to other windows, nor will it take any action that requires writing the invalid value to the server. In addition to the field-specific validations, the system allows the specification of a ValidateRecord() method for the window as a whole, for the purpose of cross-field validation. This method, if provided, is called after all the fields have passed their individual validations. The data window also provides for registering controls that are subject to the validation status. Such registered controls are disabled whenever the window's validation status is bad. The data window class also provides action methods that correspond to the general capabilities of all data servers: GoTop(), GoTo(), GoBottom(), SkipNext(), SkipPrevious(), Append(), Delete(), and so on. The data window versions of these methods verify the validation status of the controls on the window. If everything is valid, the window invokes the corresponding method of the data server. The data window provides built-in facilities for concurrency control, automatically taking and releasing record locks as appropriate. Once the appropriate mode has been selected by assigning one of the available modes to DataWindow:ConcurrencyControl, record movements and changes use the concurrency control facilities of the data server to take and release locks. If taking a lock fails because another user controls the record, the data window action fails.