Class: Ruber::DocumentList

Inherits:
Qt::Object
  • Object
show all
Includes:
Enumerable, PluginLike
Defined in:
lib/ruber/documents/document_list.rb

Overview

List of all open documents

It contains convenience methods to iterate on the open documents and to create them. Whenever possible, you should use them. In particular, when you need a document associated with a given file or URL, you should always use #document, so that if a document for that file is already installed, no new document will be created.

If, for any reason, you need to create a document using Document.new, please don’t forget to add the document to the list using #add_document.

Instance Attribute Summary

Attributes included from PluginLike

#plugin_description

Instance Method Summary collapse

Methods included from Enumerable

#find!

Methods included from PluginLike

#add_extensions_to_project, #add_options_to_project, #add_widgets_to_project, #plugin_name, #register_with_project, #remove_extensions_from_project, #remove_from_project, #remove_options_from_project, #remove_widgets_from_project, #restore_session, #session_data, #shutdown, #unload, #update_project

Constructor Details

#initialize(_manager, psf) ⇒ DocumentList

Returns a new instance of DocumentList.

Parameters:



67
68
69
70
71
 
# File 'lib/ruber/documents/document_list.rb', line 67

def initialize _manager, psf
  super Ruber[:app]
  initialize_plugin psf
  @docs = []
end

Instance Method Details

#[](key) ⇒ Document?

The document corresponding to the given key

How key is interpreted depends on its class:

  • if it’s an @Integer@, the document in the corresponding position in the list will be returned

  • if it’s a @KDE::Url@, then the document associated with that url will be returned

  • if it’s a @String@ starting with a @/@ (that is, an absolute path) then the document associated with that file will be returned

  • if it’s a string not startng with a @/@, then the document with that @document_name@ will be returned

Parameters:

Returns:

  • (Document, nil) —

    the document corresponding to key or nil if no document corresponds to it

Raises:

  • (TypeError) —

    if key is not a @String@, @Integer@ or @KDE::Url@



270
271
272
273
274
275
276
277
278
279
280
281
 
# File 'lib/ruber/documents/document_list.rb', line 270

def [] key
  case key
  when String
    if Pathname.new(key).absolute? then @docs.find{|d| d.path == key}
    else @docs.find{|d| d.document_name == key}
    end
  when KDE::Url
    @docs.find{|d| d.url == key}
  when Integer then @docs[key]
  else raise TypeError
  end
end

#add_document(doc) ⇒ Document?

Adds a new document to the list

If you use #new_document and #document to create documents, you don’t need to call this method.

Note: this method doesn’t check whether the document has already been added to the list. If so, the results may cause errors. Please, always make sure the document isn’t already in the list before calling this.

Parameters:

  • doc (Document, nil) —

    the document to add. If nil, nothing is done

Returns:



164
165
166
167
168
169
 
# File 'lib/ruber/documents/document_list.rb', line 164

def add_document doc
  if doc
    connect doc, SIGNAL('closing(QObject*)'), self, SLOT('close_document(QObject*)')
    @docs << doc
  end
end

#close_all(ask = true) ⇒ Boolean

Closes all the documents

If there are modified files and ask is true, the user will be asked whether he wants to save them (see MainWindow#save_documents). If he chooses to abort closing, nothing will be done

Parameters:

  • ask (Boolean) (defaults to: true) —

    if true, in case some files are modified, the user will be asked whether to save them. If false, no file will be saved

Returns:

  • (Boolean) —

    true if the documents were closed and false otherwise



243
244
245
246
247
248
249
250
 
# File 'lib/ruber/documents/document_list.rb', line 243

def close_all ask = true
  docs = @docs.dup
  if !ask or Ruber[:main_window].save_documents docs
    docs.each {|d| d.close false}
    true
  else false
  end
end

#document(file, create_if_needed = true) ⇒ Document?

The document for a given file or url

If there’s no open document associated with the given file or url, depending on the value of create_if_needed a new document associated with the file or url will be created. In this case, the #document_created signal will be emitted.

Parameters:

  • file (String, KDE::Url) —

    the file name or URL associated with the document. A relative file name will be expanded with respect to the current directory. A string containing a url will be interpreted as an url, not as a filename. If you need a document with a name which looks like an url, you can create an empty @KDE::Url@, then using @path=@ to set its path

  • create_if_needed (Boolean) (defaults to: true) —

    whether or not to create a document associated with file if there isn’t one

Returns:

  • (Document, nil) —

    the document associated with file. If no such document exists and create_if_needed is false, nil will be returned

Raises:

  • (ArgumentError) —

    if file is a local file, there’s no document for it, it doesn’t exist and create_if_needed is true. Note that this won’t happen if file is a remote file, even if it doesn’t exist



109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/ruber/documents/document_list.rb', line 109

def document file, create_if_needed = true
  if file.is_a? String
    url = KDE::Url.new file
    url.path = File.expand_path(file) if url.relative?
  else url = file
  end
  doc = document_for_url file
  return doc if doc or !create_if_needed
  if !doc and create_if_needed
    if url.local_file?
      raise ArgumentError, "File #{url.path} doesn't exist" unless File.exist?(url.path)
    end
    doc = Document.new Ruber[:main_window], url
    add_document doc
    emit document_created(doc)
  end
  doc
end

#document_for_file(file) ⇒ Document?

The document associated with a given file

Parameters:

  • file (String) —

    the name of the file. If it’s relative, it will be considered relative to the current directory

Returns:

  • (Document, nil) —

    the document associated with file or nil if no such document exists



306
307
308
309
 
# File 'lib/ruber/documents/document_list.rb', line 306

def document_for_file file
  file = File.expand_path file
  @docs.find{|d| d.path == file}
end

#document_for_file?(file) ⇒ Boolean

Whether there’s a document associated with a given file

Parameters:

  • file (String) —

    the name of the file (absolute or relative to the current directory)

Returns:

  • (Boolean) —

    true if there’s a document associated with file and false otherwise



368
369
370
371
 
# File 'lib/ruber/documents/document_list.rb', line 368

def document_for_file? file
  file = File.expand_path file
  @docs.any?{|d| d.path == file}
end

#document_for_url(url) ⇒ Document?

The document associated with a given URL

Parameters:

Returns:

  • (Document, nil) —

    the document associated with url or nil if no such document exists



318
319
320
 
# File 'lib/ruber/documents/document_list.rb', line 318

def document_for_url url
  @docs.find{|d| d.url == url}
end

#document_for_url?(url) ⇒ Boolean

Whether there’s a document associated with a given URL

otherwise

Parameters:

Returns:

  • (Boolean) —

    true if there’s a document associated with url and false



380
381
382
 
# File 'lib/ruber/documents/document_list.rb', line 380

def document_for_url? url
  @docs.any?{|d| d.url == url}
end

#document_with_name(name) ⇒ Document?

The document with a given name

Parameters:

  • name (String) —

    the name of the document

Returns:

  • (Document, nil) —

    the document with @document_name@ name or nil if no document with that name exists



329
330
331
 
# File 'lib/ruber/documents/document_list.rb', line 329

def document_with_name name
  @docs.find{|d| d.document_name == name}
end

#document_with_name?(name) ⇒ Boolean

Whether there’s a document with a given name

Parameters:

  • name (String) —

    of the document

Returns:

  • (Boolean) —

    true if there’s a document associated with name and false otherwise



391
392
393
 
# File 'lib/ruber/documents/document_list.rb', line 391

def document_with_name? name
  @docs.any?{|d| d.document_name == name}
end

#documents ⇒ Array<Document> Also known as: to_a

Returns a list of open documents.

Returns:



131
132
133
 
# File 'lib/ruber/documents/document_list.rb', line 131

def documents
  @docs.dup
end

#documents_with_file(which = :any) ⇒ Array<Document>

The documents which are associated with a file

which can be used to restrict the list of documents to only those associated with local or remote files:

  • if which is @:local@ only documents associated with local files will be returned;

  • if which is @:remote@ only documents associated with remoted files will be returned;

  • if which has any other value, both documents associated with local and with remote files will be returned

Parameters:

  • which (Object) (defaults to: :any) —

    which kind of documents should be included in the list

Returns:

  • (Array<Document>) —

    a list of documents associated with files, and restricted according to the value of which



346
347
348
349
350
351
352
353
354
355
356
 
# File 'lib/ruber/documents/document_list.rb', line 346

def documents_with_file which = :any
  @docs.select do |d| 
    if d.has_file?
      case which
      when :local then d.url.local_file?
      when :remote then !d.url.local_file?
      else true
      end
    end
  end
end

#each_document {|Document| ... } ⇒ DocumentList, Enumerator Also known as: each

Calls the block for each document otherwise

Yields:

Returns:

  • (DocumentList, Enumerator) —

    @self@ if called with a block; an @Enumerable@



289
290
291
292
293
294
295
 
# File 'lib/ruber/documents/document_list.rb', line 289

def each_document
  if block_given? 
    @docs.each{|d| yield d}
    self
  else self.to_enum
  end
end

#empty? ⇒ Boolean

Returns whether the document list is empty or not.

Returns:

  • (Boolean) —

    whether the document list is empty or not



139
140
141
 
# File 'lib/ruber/documents/document_list.rb', line 139

def empty?
  @docs.empty?
end

#new_document ⇒ Ruber::Document

Creates a new empty document

The document is automatically added to the list and the #document_created signal is emitted

Returns:



82
83
84
85
86
87
 
# File 'lib/ruber/documents/document_list.rb', line 82

def new_document
  doc = Document.new Ruber[:main_window]
  add_document doc
  emit document_created(doc)
  doc
end

#query_close ⇒ Boolean

Override of PluginLike#query_close

It first calls the query_close of each document’s own project, returning false as soon as one of them returns false, then attempts to save each document

Returns:

  • (Boolean) —

    true if it is all right to go on closing Ruber and false otherwise



405
406
407
408
 
# File 'lib/ruber/documents/document_list.rb', line 405

def query_close
  @docs.each{|d| return false unless d.own_project.query_close}
  Ruber[:main_window].save_documents
end

#save_documents(docs, stop_on_failure = false) ⇒ Array<Document>

Attempts to save the given documents

What happens if a document can’t be saved depends on the value of stop_on_failure: if it’s false, documents which can’t be saved are skipped, while if it’s true, this method will return as soon as one document fails to save.

Note: by can’t be saved, we mean that the user chose to save a document but, for any reason, it couldn’t be saved (for example this can happen if the user doesn’t have write permission on the file, or if the disk is full). If the user decides not to save the file, instead, it is considered a success.

Parameters:

  • docs (Array<Document>) —

    an array with the documents to save

  • stop_on_failure (Boolean) (defaults to: false) —

    what to do when a document fails to save. If true, return immediately; if false, attempt to save the remaining documents

Returns:

  • (Array<Document>) —

    an array with the documents which couldn’t be saved. If stop_on_failure is false, it contains only the documents for which saving failed; if stop_on_failure is true it also contains the documents for which saving wasn’t even attempted. If all documents were saved successfully, the array will be empty



192
193
194
195
196
197
198
199
200
201
202
203
 
# File 'lib/ruber/documents/document_list.rb', line 192

def save_documents docs, stop_on_failure = false
  failed = []
  docs.each_with_index do |d, i| 
    success = d.save
    failed << d unless success
    if !success and stop_on_failure
      failed += docs[(i+1)..-1]
      break
    end
  end
  failed
end

#save_settings ⇒ nil

Saves the settings for all open documents

Returns:

  • (nil) 


210
211
212
213
 
# File 'lib/ruber/documents/document_list.rb', line 210

def save_settings
  @docs.each{|d| d.save_settings}
  nil
end

#size ⇒ Integer Also known as: length

Returns the number of documents in the list.

Returns:

  • (Integer) —

    the number of documents in the list



146
147
148
 
# File 'lib/ruber/documents/document_list.rb', line 146

def size
  @docs.size
end