Add !-postfix to modifying methods, prefer to extends Base methods.

src/AtomShell/window.jl

@@ -1,12 +1,21 @@
 using ..Blink
 import Blink: js, id
 import JSExpr: JSString, jsstring
-import Base: position, size, close
 
 export Window, flashframe, shell, progress, title,
   centre, floating, loadurl, opentools, closetools, tools,
   loadhtml, loadfile, css, front
 
+# Keep sorted
+export
+    center!,
+    loadfile!,
+    loadurl!,
+    opentools!,
+    position!,
+    progress!,
+    title!
+
 mutable struct Window
   id::Int
   shell::Shell
@@ -20,7 +29,7 @@ end
 
 Create and open a new Window through Electron.
 
-If `async==false`, this function blocks until the Window is fully initialized
+If `async=false`, this function blocks until the Window is fully initialized
 and ready for you to communicate with it via javascript or the Blink API.
 
 The `electron_options` dict is used to initialize the Electron window. See here
@@ -29,8 +38,8 @@ https://electronjs.org/docs/api/browser-window#new-browserwindowoptions
 """
 function Window end
 
-shell(win::Window) = win.shell
-id(win::Window) = win.id
+shell(window::Window) = window.shell
+id(window::Window) = window.id
 
 const window_defaults = @d(:url => "about:blank",
                            :title => "Julia",
@@ -117,7 +126,7 @@ end
 # Window management APIs
 
 """
-    active(win::Window)::Bool
+    active(window::Window)::Bool
     active(connection)::Bool
 
 Indicates whether the specified `Window` (or `Page`, `shell`, or other internal component)
@@ -140,111 +149,185 @@ function active end
 active(s::Electron, win::Integer) =
   @js s windows.hasOwnProperty($win)
 
-active(win::Window) = active(shell(win), id(win))
+active(window::Window) = active(shell(window), id(window))
 
 """
-    flashframe(win::Window, on=true)
+    flashframe!(window::Window, on::Bool=true)
 
 Start or stop "flashing" the window to get the user's attention.
 
-In Windows, flashes the window frame. In MacOS, bounces the app in the Dock.
-https://github.com/electron/electron/blob/master/docs/api/browser-window.md#winflashframeflag
+In Windows, this flashes the window frame.
+In MacOS, this bounces the app in the Dock.
+
+See the [Electron `flashFrame` documentation](https://github.com/electron/electron/blob/master/docs/api/browser-window.md#winflashframeflag) for details.
 """
-flashframe(win::Window, on = true) =
-  @dot_ win flashFrame($on)
+# TODO: Maybe rename this to `flash_frame!`
+# The "general advice" is that only Base is allowed to define methods that elide
+# the underscore (https://github.com/invenia/BlueStyle).
+flashframe!(window::Window, on::Bool=true) = @dot_ window flashFrame($on)
+
+# Deprecated
+flashframe(window::Window, on::Bool=true) = flashframe!(window, on)
 
 """
-    progress(win::Window, p=-1)
+    progress!(window::Window, progress)
 
 Sets progress value in progress bar. Valid range is [0, 1.0]. Remove progress
-bar when progress < 0; Change to indeterminate mode when progress > 1.
+bar when progress < 0; Change to _indeterminate mode_ when progress > 1.
 
-https://github.com/electron/electron/blob/master/docs/api/browser-window.md#winsetprogressbarprogress-options
+See the [Electron `setProgressBar` documentation](https://github.com/electron/electron/blob/master/docs/api/browser-window.md#winsetprogressbarprogress-options) for details.
 """
-progress(win::Window, p = -1) =
-  @dot_ win setProgressBar($p)
+progress!(window::Window, progress) = @dot_ window setProgressBar($progress)
+
+# Deprecated
+progress(window::Window, progress=-1) = progress!(win, progress)
 
 """
-    title(win::Window, title)
+    title!(window::Window, title)
 
-Set `win`'s title to `title.`
+Set the window's title.
 """
-title(win::Window, title) =
-  @dot_ win setTitle($title)
+title!(window::Window, title) = @dot_ window setTitle($title)
+
+# Deprecated
+title(window::Window, title) = title!(window, title)
 
 """
-    title(win::Window)
+    title(window::Window)
 
 Get the window's title.
 """
-title(win::Window) =
-  @dot win getTitle()
+title(window::Window) = @dot window getTitle()
+
+"""
+    center!(window::Window)
+
+Center a window on the screen.
+"""
+center!(window::Window) = @dot_ window center()
+
+# Deprecated (and misspelled?)
+centre(window::Window) =
+  @dot_ window center()
+
+"""
+    position!(window, x, y)
+    position!(window, position)
+
+Position a window.
+
+This positions the top-left corner of the window to match the given coordinates.
+"""
+position!(w::Window, x, y) = @dot_ w setPosition($x, $y)
+position!(w::Window, pos) = position!(w, pos...)
+
+# Deprecated
+position(w::Window, x, y) = position!(w, x, y)
+
+"""
+    position(window)
 
-centre(win::Window) =
-  @dot_ win center()
+Get the window's position.
 
-position(win::Window, x, y) =
-  @dot_ win setPosition($x, $y)
+This returns a tuple that represents the position of the top-left corner of the
+window.
+"""
+function position(window::Window)
+    x, y = Int.(@dot window getPosition())
+    return (x, y)
+end
 
-position(win::Window) =
-  @dot win getPosition()
+"""
+    resize!(window::::Window, width, height)
+    resize!(window::::Window, dims)
 
-size(win::Window, w::Integer, h::Integer) =
-  invoke(size, Tuple{Window, Any, Any}, win, w, h)
+Resize a window to the given dimensions.
+"""
+function Base.resize!(window::Window, width, height)
+    @dot_ window setSize($width, $height)
+end
+Base.resize!(window::Window, dims) = resize!(window, dims...)
 
-size(win::Window, w, h) =
-  @dot_ win setSize($w, $h)
+# Deprecated
+Base.size(window::Window, width, height) = resize!(window, width, height)
+
+# Deprecated
+# This is required for Julia 0.7 due to ambiguity error with a deprecated
+# method for Base.size.
+function Base.size(window::Window, width::Integer, height::Integer)
+    resize!(window, (width, height))
+end
+
+"""
+    size(window::Window)
 
-size(win::Window) =
-  @dot win getSize()
+Return a tuple with the dimensions of the window.
+"""
+function Base.size(window::Window)
+    width, height = Int.(@dot window getSize())
+    return (width, height)
+end
 
-floating(win::Window, flag) =
-  @dot_ win setAlwaysOnTop($flag)
+# TODO: What's a good !-method for this setter function?
+# Maybe `pin!` or `always_on_top!`?
+floating(window::Window, flag) =
+  @dot_ window setAlwaysOnTop($flag)
 
-floating(win::Window) =
-  @dot win isAlwaysOnTop()
+floating(window::Window) =
+  @dot window isAlwaysOnTop()
 
-loadurl(win::Window, url) =
-  @dot win loadURL($url)
+loadurl!(window::Window, url) = @dot window loadURL($url)
+loadurl(window::Window, url) = loadurl!(win, url)
 
-loadfile(win::Window, f) =
-  loadurl(win, "file://$f")
+loadfile!(window::Window, f) = loadurl(win, "file://$f")
+loadfile(window::Window, f) = loadfile!(win, f)
 
 """
-    opentools(win::Window)
+    opentools!(window::Window)
 
 Open the Chrome Developer Tools on `win`.
 
 See also: [`closetools`](@ref), [`tools`](@ref)
 """
-opentools(win::Window) =
-  @dot win openDevTools()
+# TODO: Maybe rename to open_tools!
+opentools!(w::Window) = @dot window openDevTools()
+opentools(w::Window) = opentools!(w)
 
 """
-    closetools(win::Window)
+    closetools(window::Window)
 
 Close the Chrome Developer Tools on `win` if open.
 
 See also: [`opentools`](@ref), [`tools`](@ref)
 """
-closetools(win::Window) =
-  @dot win closeDevTools()
+closetools!(window::Window) = @dot window closeDevTools()
+closetools(window::Window) = closetools!(win)
 
 """
-    tools(win::Window)
+    tools!(window::Window)
 
 Toggle the Chrome Developer Tools on `win`.
 
 See also: [`opentools`](@ref), [`closetools`](@ref)
 """
-tools(win::Window) =
-  @dot win toggleDevTools()
+tools!(window::Window) = @dot window toggleDevTools()
+tools(window::Window) = tools!(win)
 
-front(win::Window) =
-  @dot win showInactive()
 
-close(win::Window) =
-  @dot win close()
+"""
+    front!(window::Window)
+
+Bring a window to the front of the desktop without focusing it.
+"""
+front!(window::Window) = @dot window showInactive()
+front(window::Window) = front!(window)
+
+"""
+    close(window::Window)
+
+Close a window.
+"""
+Base.close(window::Window) = @dot window close()
 
 # Window content APIs
 
@@ -262,7 +345,7 @@ const initcss = """
   <style>html,body{margin:0;padding:0;border:0;text-align:center;}</style>
   """
 
-function loadhtml(win::Window, html::AbstractString)
+function loadhtml!(win::Window, html::AbstractString)
   tmp = string(tempname(), ".html")
   open(tmp, "w") do io
     println(io, initcss)
@@ -272,3 +355,4 @@ function loadhtml(win::Window, html::AbstractString)
   @async (sleep(1); rm(tmp))
   return
 end
+loadhtml(win::Window, html::AbstractString) = loadhtml!(win, html)

test/AtomShell/window.jl

@@ -6,10 +6,10 @@ using Test
 # unknown reasons.
 w = Window(Blink.@d(:show => false, :width=>150, :height=>100), async=false);
 @testset "size Tests" begin
-    @test size(w) == [150,100]
+    @test size(w) == (150, 100)
 
-    size(w, 200,200)
-    @test size(w) == [200,200]
+    size(w, 200, 200)
+    @test size(w) == (200, 200)
 end
 
 # @testset "async" begin