From 2f4cca445b2145d6bca0e3ff52a2a2d5b4818541 Mon Sep 17 00:00:00 2001 From: Matt Colyer Date: Thu, 22 Aug 2013 15:01:18 -0700 Subject: [PATCH] Document AtomApplication --- src/atom-application.coffee | 121 ++++++++++++++++++++++++++++++++++++ 1 file changed, 121 insertions(+) diff --git a/src/atom-application.coffee b/src/atom-application.coffee index 1b9f8f7ec..4ecb393aa 100644 --- a/src/atom-application.coffee +++ b/src/atom-application.coffee @@ -15,10 +15,40 @@ _ = require 'underscore' socketPath = '/tmp/atom.sock' +# Public: The application's singleton class. +# +# It's the entry point into the Atom application and maintains the global state +# of the application. For the most part you won't interact directly with this +# class but you may use one it's provided commands. +# +# ## Commands +# +# * `application:about` - This opens the about dialog. +# * `application:show-settings` - This opens the preference pane in the currently +# focused editor. +# * `application:quit` - This quits the entire application. +# * `application:hide` - This hides the entire application. +# * `application:hide-other-applications` - This hides other applications +# running on the system. +# * `application:unhide-other-applications` - This shows other applications +# that were previously hidden. +# * `application:new-window` - This opens a new {AtomWindow} with no {Project} +# path. +# * `application:new-file` - This creates a new file within the focused window. +# Note: only one new file may exist within an {AtomWindow} at a time. +# * `application:open` - Prompts the user for a path to open in a new {AtomWindow} +# * `application:minimize` - Minimizes the currently focused {AtomWindow} +# * `application:zoom` - Expands the window to fill the screen or returns it to +# it's original unzoomed size. +# * `application:bring-all-windows-to-front` - Brings all {AtomWindow}s to the +# the front. module.exports = class AtomApplication _.extend @prototype, EventEmitter.prototype + # Public: The entry point into the Atom application. + # + # Returns nothing. @open: (options) -> createAtomApplication = -> new AtomApplication(options) @@ -65,14 +95,31 @@ class AtomApplication else @openPath({pidToKillWhenClosed, newWindow, devMode}) # Always open a editor window if this is the first instance of Atom. + # Public: Removes a window from the global window list. + # + # window - The relevant {AtomWindow} + # + # Returns nothing. removeWindow: (window) -> @windows.splice @windows.indexOf(window), 1 @applicationMenu?.enableWindowSpecificItems(false) if @windows.length == 0 + # Public: Adds a window to the global window list. + # + # window - The relevant {AtomWindow} + # + # Returns nothing. addWindow: (window) -> @windows.push window @applicationMenu?.enableWindowSpecificItems(true) + # Private: Creates server to listen for additional atom application launches. + # + # You can run the atom command multiple times, but after the first launch + # the other launches will just pass their information to this server and then + # close immediately. + # + # Returns nothing. listenForArgumentsFromNewProcess: -> fs.unlinkSync socketPath if fs.existsSync(socketPath) server = net.createServer (connection) => @@ -83,9 +130,17 @@ class AtomApplication server.listen socketPath server.on 'error', (error) -> console.error 'Application server failed', error + # Private: Configures required javascript environment flags. + # + # Returns nothing. setupJavaScriptArguments: -> app.commandLine.appendSwitch 'js-flags', '--harmony_collections' + # Private: Determines whether the auto updater should check for updates. + # + # If running from a local build, we don't want to update to a released version. + # + # Returns nothing. checkForUpdates: -> versionIsSha = /\w{7}/.test @version @@ -97,6 +152,11 @@ class AtomApplication autoUpdater.setAutomaticallyChecksForUpdates true autoUpdater.checkForUpdatesInBackground() + # Private: Registers basic application commands. + # + # This should only be called once. + # + # Returns nothing. handleEvents: -> @on 'application:about', -> Menu.sendActionToFirstResponder('orderFrontStandardAboutPanel:') @on 'application:run-all-specs', -> @runSpecs(exitWhenDone: false, resourcePath: global.devResourcePath) @@ -146,20 +206,57 @@ class AtomApplication ipc.on 'command', (processId, routingId, command) => @emit(command) + # Public: Executes the given command. + # + # If it isn't handled globally, delegate to the currently focused window. + # + # command - The string representing the command. + # args - The optional arguments to pass along. + # + # Returns nothing. sendCommand: (command, args...) -> unless @emit(command, args...) @focusedWindow()?.sendCommand(command, args...) + # Private: Selects the window based on the given path. + # + # pathToOpen - The full file path used to select the window. + # + # FIXME: This should probably return undefined if no window is found. + # + # Returns the {AtomWindow} which is opened to the selected path and the list + # of windows otherwise. windowForPath: (pathToOpen) -> for atomWindow in @windows return atomWindow if atomWindow.containsPath(pathToOpen) + # Public: Finds the currently focused window. + # + # Returns the currently focused {AtomWindow} or undefined if none are focused. focusedWindow: -> _.find @windows, (atomWindow) -> atomWindow.isFocused() + # Public: Opens multiple paths, in existing windows if possible. + # + # options - + # pathsToOpen: The array of file paths to open + # pidToKillWhenClosed: The integer of the pid to kill + # newWindow: Boolean of whether this should be opened in a new window. + # devMode: Boolean to control the opened window's dev mode. + # + # Returns nothing. openPaths: ({pathsToOpen, pidToKillWhenClosed, newWindow, devMode}) -> @openPath({pathToOpen, pidToKillWhenClosed, newWindow, devMode}) for pathToOpen in pathsToOpen ? [] + # Public: Opens a single path, in an existing window if possible. + # + # options - + # pathsToOpen: The array of file paths to open + # pidToKillWhenClosed: The integer of the pid to kill + # newWindow: Boolean of whether this should be opened in a new window. + # devMode: Boolean to control the opened window's dev mode. + # + # Returns nothing. openPath: ({pathToOpen, pidToKillWhenClosed, newWindow, devMode}={}) -> unless devMode existingWindow = @windowForPath(pathToOpen) unless pidToKillWhenClosed or newWindow @@ -186,6 +283,13 @@ class AtomApplication console.log("Killing process #{pid} failed: #{error.code}") delete @pidsToOpenWindows[pid] + # Private: Handles an atom:// url. + # + # Currently only supports atom://session/ urls. + # + # options - + # urlToOpen: The atom:// url to open. + # devMode: Boolean to control the opened window's dev mode. openUrl: ({urlToOpen, devMode}) -> parsedUrl = url.parse(urlToOpen) if parsedUrl.host is 'session' @@ -197,6 +301,14 @@ class AtomApplication else console.log "Opening unknown url #{urlToOpen}" + # Private: Opens up a new {AtomWindow} to run specs within. + # + # options - + # exitWhenDone: A Boolean that if true, will close the window upon completion. + # resourcePath: The path to include specs from. + # specPath: The directory to load specs from. + # + # Returns nothing. runSpecs: ({exitWhenDone, resourcePath, specPath}) -> if resourcePath isnt @resourcePath and not fs.existsSync(resourcePath) resourcePath = @resourcePath @@ -206,6 +318,15 @@ class AtomApplication devMode = true new AtomWindow({bootstrapScript, resourcePath, exitWhenDone, isSpec, devMode, specPath}) + # Private: Opens a native dialog to prompt the user for a path. + # + # Once paths are selected, they're opened in a new or existing {AtomWindow}s. + # + # options - + # devMode: A Boolean which controls whether any newly opened windows should + # be in dev mode or not. + # + # Returns nothing promptForPath: ({devMode}={}) -> pathsToOpen = dialog.showOpenDialog title: 'Open', properties: ['openFile', 'openDirectory', 'multiSelections', 'createDirectory'] @openPaths({pathsToOpen, devMode})