DocumentSvc.I Interface
- public static interface DocumentSvc.I
-
Enclosing class
-
DocumentSvc
public IDocumentView |
-
displayDocument (IDocument doc, boolean fActivate)
- Displays the given document to the user.
|
public IDocumentView |
-
displayDocument (IDocument doc)
- Displays the given document to the user.
|
public IDocumentView |
-
displayDocument (IDocument doc, String viewName)
- Makes the requested document view object active.
|
public IDocumentView |
-
displayDocument (IDocument doc, String viewName, INavigationPoint navPoint)
- Makes the requested document view active, and select the follow to
the requested navigation point.
|
public IDocumentView |
-
displayDocument (URI uriFile)
- Displays the given file to the user.
|
public URI [] |
-
getDisplayedDocuments ()
- Obtains an array of all currently open documents.
|
public URI [] |
-
getDisplayedDocumentsZorder ()
- Obtains an array of all currently open documents.
|
public IDocumentInfo |
-
getDocInfo (URI uriFile)
- Gets the
IDocumentInfo for the given file.
|
public IDocumentInfo |
-
getDocInfo (String sHandlerId)
- Gets the
IDocumentInfo for the given document handler.
|
public IDocument |
-
getDocument (URI uriFile, String sHandlerId)
- Opens a file using the specified document handler.
|
public IDocument |
-
getDocument (URI uriFile)
- Opens a file using the default document handler for the file.
|
public String |
-
getDocumentViewName (IDocument doc, IDocumentView view)
- Finds the string name of the given document view.
|
public IDocument |
-
getExistingDocument (URI uriFile)
- Obtains an already existing document for a file.
|
public IDocumentView |
-
getExistingDocumentView (IDocument doc, String viewName)
- Gets a reference to a document view by name.
|
public URI [] |
-
getOpenDocuments ()
- Obtains an array of all currently open documents.
|
public void |
-
hideDocument (IDocument doc)
- Closes the document so that it is no longer visible to the user.
|
public boolean |
-
hideDocumentDialog (IDocument doc)
- Closes the document so that it is no longer visible to the user.
|
public void |
-
hideDocuments (URI [] rguri)
- Closes the provided documents so that they are no longer visible to the user.
|
public void |
-
hideDocumentsDialog (URI [] rguri)
- Closes the provided documents so that they are no longer visible to the user.
|
public boolean |
-
isActiveDocumentView (IDocument doc, String viewName)
- Determines if a document view is the currently active view.
|
public boolean |
-
isDisplayed (IDocument doc)
- Determines whether or not a specified document is currently displayed.
|
public boolean |
-
isDisplayed (URI uriFile)
- Determines whether or not a specified URI is currently displayed.
|
public boolean |
-
isLoaded (URI uriFile)
- Returns true if the document is actually loaded in memory.
|
public boolean |
-
isModified (URI uriFile)
- Determines whether or not a specified URI is modified.
|
public boolean |
-
isValidExtension (String sHandlerId, String sFileExt)
- Returns a boolean indicating whether the given extension is valid for the given handler.
|
public IDocument |
-
newDocument (URI uriName, String sHandlerId)
- Creates a new document using the specified handler.
|
public IDocument |
-
newDocument (URI uriName, String sHandlerId, String sTemplateId)
- Creates a new document using the specified handler.
|
public void |
-
refreshUndoState ()
- Refreshes the undo state for the currently active view.
|
public void |
-
replaceDocument (IDocument docOld, IDocument docNew)
- Replaces a particular document in the document panel with another document.
|
public boolean |
-
saveAllDialog ()
- Saves all documents that have unsaved modifications.
|
public boolean |
-
saveDocument (IDocument doc)
- Saves the document.
|
public boolean |
-
saveDocumentDialog (IDocument doc)
- Saves the document.
|
displayDocument(IDocument, boolean) Method
public IDocumentView
displayDocument(IDocument
doc,
boolean fActivate)
Displays the given document to the user. This document should have been previously opened by a call to
DocumentSvc.I.getDocument(URI, String)
. The document service will instantiate the views of the document if
it is not currently visible. The currently active view for the document will either be the last view shown,
the first view in it's list (if it was previously not visible). Furthermore, if fActivate is true, it
will bring the view to the front and give it the keyboard focus. Note that if this is the only visible
document, the fActivate parameter is ignored.
Parameters
-
doc
- Document to display.
-
fActivate
- Boolean indicating whether or not the document view should become the currently active view
Returns
- The document being displayed.
displayDocument(IDocument) Method
public IDocumentView
displayDocument(IDocument
doc)
Displays the given document to the user. This document should have been previously opened by a call to
DocumentSvc.I.getDocument(URI, String)
. The document service will instantiate the views of the document if
it is not currently visible. The currently active view for the document will either be the last view shown,
the first view in it's list (if it was previously not visible). The view will be brought to the front and
given the keyboard focus. This method is equivalent to calling DocumentSvc.I.displayDocument(IDocument, boolean)
with fActivate = true.
Parameters
-
doc
- Document to display.
Returns
- The document being displayed.
displayDocument(IDocument, String) Method
public IDocumentView
displayDocument(IDocument
doc,
String
viewName)
Makes the requested document view object active. If there are multiple instances of
this view open there is a hierarchy to determine which one is activated and returned
-- An instance of the currently active view in the active document panel
-- An instance of the currently active view in the non-active document panel
-- An instance of an non-active view in the active document panel
-- An instance of an non-active view in the non-active document panel
Parameters
-
doc
- Document to display.
-
viewName
- String name of the document view to display
Returns
- The document view requested, or null if it does not exist
displayDocument(IDocument, String, INavigationPoint) Method
public IDocumentView
displayDocument(IDocument
doc,
String
viewName,
INavigationPoint
navPoint)
Makes the requested document view active, and select the follow to
the requested navigation point. The navpoint can be anything that
the view understands. Also, it doesn't necessarily have to know
about the view, since the code tells the view to act on the navpoint.
If there are multiple instances of this view open there is a hierarchy
to determine which one is activated and returned. See above.
Parameters
-
doc
- Document to display.
-
viewName
- String name of the document view to display
-
navPoint
- is a navigation point appropriate for when the
caller doesn't yet have a view pointer.
Returns
- The document view requested, or null if it does not exist
displayDocument(URI) Method
public IDocumentView
displayDocument(URI
uriFile)
Displays the given file to the user. The file will first be opened by the default document handler and
then displayed. This is equivalent to first calling
DocumentSvc.I.getDocument(URI)
and then calling
DocumentSvc.I.displayDocument(IDocument)
. If the file cannot be opened, nothing will
be displayed and the method will return null.
The document service will obtain the views for the document and
either reshow the last view for the document, or show the first view in it's list. If the document is
already visible, this will simply bring it to the front and give it the keyboard focus.
Parameters
-
uriFile
- The file that should be opened and displayed.
Returns
- The document being displayed or null if the file could not be opened.
getDisplayedDocuments() Method
public URI
[] getDisplayedDocuments()
Obtains an array of all currently open documents. This method allows you to obtain all document interfaces
that are currently visible in the document panels. The array returned is a snapshot of the system at the
time of the call and may change. The array is ordered in the order the documents were opened by the user.
Returns
- An Array containing the
IDocument
interface for each file that is displayed.
getDisplayedDocumentsZorder() Method
public URI
[] getDisplayedDocumentsZorder()
Obtains an array of all currently open documents. This method allows you to obtain all document interfaces
that are currently visible in the document panels. The array returned is a snapshot of the system at the
time of the call and may change. The array is ordered in a most recently used order.
Returns
- An Array containing the
IDocument
interface for each file that is displayed.
getDocInfo(URI) Method
public IDocumentInfo
getDocInfo(URI
uriFile)
Gets the IDocumentInfo
for the given file. This method looks up
the handler for the given file and returns its IDocumentInfo
interface.
If there is no handler registered for the specified file, null is returned.
Parameters
-
uriFile
- The URI for the file to look up
Returns
- An
IDocumentInfo
interface for the specified file or null if there is no handler
registered for the file.
getDocInfo(String) Method
public IDocumentInfo
getDocInfo(String
sHandlerId)
Gets the IDocumentInfo
for the given document handler.
Parameters
-
sHandlerId
- The string name of the document handler
Returns
- An
IDocumentInfo
interface for the specified handler.
getDocument(URI, String) Method
public IDocument
getDocument(URI
uriFile,
String
sHandlerId)
Opens a file using the specified document handler. The document handler will be used
to create the document interface for the given file. If a document has already been opened, that
document is simply returned. Note that a document interface simply creates a programmatic interface
to the file. To display a document to the user use
DocumentSvc.I.displayDocument(URI)
.
Parameters
-
uriFile
- The uri for the file to be opened
-
sHandlerId
- The string name of the document handler that should be used to open the file.
Returns
- The
IDocument
interface of the opened document or null if the handler cannot be found
or is unable to open the file
getDocument(URI) Method
public IDocument
getDocument(URI
uriFile)
Opens a file using the default document handler for the file. The document handler will be used
to create the document interface for the given file. If a document has already been opened, that
document is simply returned. Note that a document interface simply creates a programmatic inteface
to the file. To display a document to the user use
DocumentSvc.I.displayDocument(URI)
.
Parameters
-
uriFile
- The uri for the file to be opened
Returns
- The
IDocument
interface of the opened document or null if a handler cannot be found
or is unable to open the file
getDocumentViewName(IDocument, IDocumentView) Method
public String
getDocumentViewName(IDocument
doc,
IDocumentView
view)
Finds the string name of the given document view. One should be able to use this to retrieve the
view for a particular document, regardless of whether the document has remained in memory
or not.
getExistingDocument(URI) Method
public IDocument
getExistingDocument(URI
uriFile)
Obtains an already existing document for a file. This method allows you to obtain a document interface for a file
only if that file has already been opened. For files that have not been opened, or were garbage collected,
this method will return null.
Parameters
-
uriFile
- The uri for the file for which the existing document should be located.
Returns
- The
IDocument
interface of the existing document or null there is no open document.
getExistingDocumentView(IDocument, String) Method
public IDocumentView
getExistingDocumentView(IDocument
doc,
String
viewName)
Gets a reference to a document view by name. This method will find an existing IDocumentView using the
same algorithm outlined above for displayDocument. It will then return the view. This method does not
alter the visible state of the document. If the document is not currently displayed, this method will
return null.
Parameters
-
doc
- Document to retrieve the view for
-
viewName
- The name of the view, as it is listed in the IDocumentViewInfo of the document
Returns
- IDocumentView interface to the specified view, or null if the view name does not exist or the document
or the document is not displayed
getOpenDocuments() Method
public URI
[] getOpenDocuments()
Obtains an array of all currently open documents. This method allows you to obtain all document interfaces
that are currently open within the system. Note that documents may be open even if they are not visible to
the user. If you want to get a list of all user visible documents, use DocumentSvc.I.getDisplayedDocuments()
.
Returns
- An Array containing the
IDocument
interface for each file that is open.
hideDocument(IDocument) Method
public void hideDocument(IDocument
doc)
Closes the document so that it is no longer visible to the user. If the document has unsaved modifications,
this method will discard the changes. Note that this method does not cause the document object to become
unavailable. It simply removes the views from the IDE. When there are no further references to the
IDocument, it will be garbage collected automatically. If the given document is not currently visible,
this method will simply return.
Parameters
-
doc
- The document to hide
hideDocumentDialog(IDocument) Method
public boolean hideDocumentDialog(IDocument
doc)
Closes the document so that it is no longer visible to the user. If the document has unsaved modifications,
this method will pop up a dialog requesting action from the user on whether the changes should be discarded.
Note that this method does not cause the document object to become unavailable. It simply removes the
views from the IDE. When there are no further references to the IDocument, it will be garbage collected
automatically. If the given document is not currently visible, this method will simply return.
Parameters
-
doc
- The document to hide
Returns
- true to indicate that the file was closed. false if the user cancelled the close.
hideDocuments(URI[]) Method
public void hideDocuments(URI
[] rguri)
Closes the provided documents so that they are no longer visible to the user. If the documents have unsaved modifications,
this method will discard the changes after hiding the views. Note that this method does not cause the
document objects to become unavailable. It simply removes the views from the IDE. When there are no
further references to the IDocuments, they will be garbage collected automatically.
Parameters
-
rguri
- Array of uris for the documents that should be hidden
hideDocumentsDialog(URI[]) Method
public void hideDocumentsDialog(URI
[] rguri)
Closes the provided documents so that they are no longer visible to the user. If the documents have unsaved modifications,
this method will pop up a dialog requesting action from the user on whether the changes should be discarded.
Note that this method does not cause the document objects to become unavailable. It simply removes the views
from the IDE. When there are no further references to the IDocuments, they will be garbage collected automatically.
Parameters
-
rguri
- Array of uris for the documents that should be hidden
isActiveDocumentView(IDocument, String) Method
public boolean isActiveDocumentView(IDocument
doc,
String
viewName)
Determines if a document view is the currently active view. This has the benefit of not
forcing the view to be instantiated.
Parameters
-
doc
- The document itself
-
viewName
- The name of the view, as it appears to the user
Returns
- Boolean indicating whether the specified view is active
isDisplayed(IDocument) Method
public boolean isDisplayed(IDocument
doc)
Determines whether or not a specified document is currently displayed. This method returns the state
at the instance of the call. Note that display does not mean it is currently visible, merely that
it is in the list of open documents that are visible to the user.
Returns
- True if the given document is currently displayed to the user, false otherwise.
isDisplayed(URI) Method
public boolean isDisplayed(URI
uriFile)
Determines whether or not a specified URI is currently displayed. This method returns the state
at the instance of the call. Note that display does not mean it is currently visible, merely that
it is in the list of open documents that are visible to the user.
Returns
- True if the given document is displayed to the user, false otherwise.
isLoaded(URI) Method
public boolean isLoaded(URI
uriFile)
Returns true if the document is actually loaded in memory. The set of documents that are loaded is a subset
of the documents that are open. The document may or may not also be in the visible set. Documents are open
but not loaded when they are lazily loaded on startup. They appear in the UI and in lists, but are not
physically loaded. Note that it is impossible for a non-loaded document to be dirty. They are by definition
unmodified. This method may be used to avoid bringing in a lazily loaded document if the operation on the
document can be avoided until the document is in memory.
Parameters
-
uriFile
- The uri for the file that should be checked
Returns
- true if the given URI represents an in memory document (obtain via getDocument or getExistingDocument)
false if the URI is either not open, or is open, but not yet loaded int memory.
isModified(URI) Method
public boolean isModified(URI
uriFile)
Determines whether or not a specified URI is modified. This allows someone
to check a file obtained through getDisplayedDocuments(). This method will always
return false if the document is not currently in memory.
Parameters
-
uriFile
- The URI of the document to check
Returns
- boolean indicating whether or not the URI's in-memory image has changed
compared to its backing store
isValidExtension(String, String) Method
public boolean isValidExtension(String
sHandlerId,
String
sFileExt)
Returns a boolean indicating whether the given extension is valid for the given handler. A true
return value does not mean that the given handler is the canonical handler for the extension, merely
that it is registered as able to open it.
Parameters
-
sHandlerId
- ID of the handler to check
-
sFileExt
- String representing the file extension (trailing characters after the last .)
Returns
- true if the given extension is registered as a valid extension for the given handler,
false otherwise.
newDocument(URI, String) Method
public IDocument
newDocument(URI
uriName,
String
sHandlerId)
Creates a new document using the specified handler. This allows the user to create a new file of
a specific type. This is identical to calling the three parameter version with null as the
sTemplateId value.
Parameters
-
uriName
- The string name of the document handler.
Returns
- A new document interface created by the specified handler or null if there was an error.
newDocument(URI, String, String) Method
public IDocument
newDocument(URI
uriName,
String
sHandlerId,
String
sTemplateId)
Creates a new document using the specified handler. This allows the user to create a new file of
a specific type. The template string is an id that is used to identify to the document any
sub-category. The null value may be used for the template ID to indicate the default.
Parameters
-
uriName
- The path to the new file.
-
sHandlerId
- The string name of the document handler.
-
sTemplateId
- A template name known to the handler for specifying template contents
Returns
- A new document interface created by the specified handler or null if there was an error.
refreshUndoState() Method
public void refreshUndoState()
Refreshes the undo state for the currently active view. This will force the undo and redo actions to be updated
in accordance with the state of the undo manager on the current document.
replaceDocument(IDocument, IDocument) Method
public void replaceDocument(IDocument
docOld,
IDocument
docNew)
Replaces a particular document in the document panel with another document. Used for
save and rename operations where the URI the user is operating on changes
Parameters
-
docOld
- The old document that is being replaced
-
docNew
- The new instance of the document that should be used
saveAllDialog() Method
public boolean saveAllDialog()
Saves all documents that have unsaved modifications. This is an extension of saveDocumentDialog
that will attempt to save all documents for which IDocument.isModified() returns true. Note that
if the user cancels this operation some of the documents may be saved and some may not.
Returns
- Boolean indicating whether all documents were saved.
saveDocument(IDocument) Method
public boolean saveDocument(IDocument
doc)
Saves the document. The document's onSave method will be called to verify that it is currently in a state that
it may be saved.
Parameters
-
doc
- The document to save
Returns
- Boolean indicating whether the document was actually saved. The document may override the save.
saveDocumentDialog(IDocument) Method
public boolean saveDocumentDialog(IDocument
doc)
Saves the document. This method differs from DocumentSvc.I.saveDocument(IDocument)
in that it may interact with the user if
the document cannot be saved. It is intended to be used to respond to user input that indicates the document should
be saved.
Parameters
-
doc
- The document to save
Returns
- Boolean indicating whether the document was actually saved. The user may cancel the save in some manner