TDocument provides two functions for working with views, TDocument::NotifyViews() and TDocument::QueryViews().

Both functions take three parameters, an int corresponding to an event, a long item, and a TView *. The meaning of the long item is dependent on the event and is essentially a parameter to the event. The TView * lets you exclude a view from your query or notification by passing a pointer to that view to the function. These two functions are your primary means of communicating information between your document and its views.

Both functions call views through the views' response tables. The general-purpose macro used for ObjectWindows notification events is EV_OWLNOTIFY. The response functions for EV_OWLNOTIFY events have the following signature:

bool FnName(long);

VarType

Definition safearray.h:14

The long item used in the NotifyViews or QueryViews function call is used for the long parameter for the response function.

You can use NotifyViews to notify your child documents, their associated views, and the associated views of your root document of a change in data, an update, or any other event that might need to be reflected onscreen. The meaning of the event and the accompanying item passed as a parameter to the event are implementation defined.

NotifyViews first calls all the document's child documents' NotifyViews functions, which are called with the same parameters. After all the children have been called, NotifyViews passes the event and item to all of the document's associated views. NotifyViews returns a bool. If any child document or associated view returns false, NotifyViews returns false. Otherwise NotifyViews returns true.

QueryViews sends an event and accompanying parameter just like NotifyViews. The difference is that, whereas NotifyViews returns true when any child or view returns true, QueryViews returns a pointer to the first view that returns true. This behavior makes QueryViews useful for finding a view that meets some condition and then performing some action on that view. If no views return true, QueryViews returns 0.

Another difference between NotifyViews and QueryViews is that NotifyViews always sends the event and its parameter to all children and associated views, while QueryViews stops at the first view that returns true.

Example

Suppose you have a document class that contains graphics data in a bitmap. You want to know which of your associated views is displaying a certain area of the current bitmap. You can define an event such as WM_CHECKRECT. Then you can set up a TRect structure containing the coordinates of the rectangle you want to check for. The excerpted code would look something like this:

DEFINE_RESPONSE_TABLE1(TMyView, TView)
 
  .
  .
  .
 EV_OWLNOTIFY(WM_CHECKREST, EvCheckRest),
 
  .
  .
  .
END_RESPONSE_TABLE;
 
void MyDocClass::Function() {
 // Set up a TRect * with the coordinates you want to send.
 TRect *rect = new TRect(100, 100, 300, 300);
 
 // QueryViews
 TView *view = QueryViews(WM_CHECKRECT, (long) rect);
 
 // Clear all changes from the view
 if(view)
  view->Clear();
}
 
// The view response function gets the pointer to the rectangle
// as the long parameter to its response function.
bool TMyView::EvCheckRest(long item) {
 TRect *rect = (TRect *) item;
 
 // Check to see if rect is equal to this view's rect.
 if(*rect == this->rect)
  return true;
 else
  return false;
}

You can also set up your own event macros to handle view notifications, as described in Doc/View Event Handling.

Example

See Also