Transcript
[ Music ]
>> Good morning, everyone.
[ Applause ]
Wow.
Thank you.
Welcome to Advanced Dark Mode.
I'm Matt Jacobson.
I'll be joined later on stage by
my colleague, Jeff Nadeau.
We're engineers in the Cocoa
Frameworks group at Apple.
We are super excited to talk to
you today about the awesome Dark
Mode in Mojave.
Now, in the intro session
yesterday, you learned all the
things you need to get started
adapting your app for Dark Mode,
like rebuilding on the macOS
10.14 SDK.
Making use of dynamic colors
instead of static or hardcoded
colors.
Making correct use of template
images and materials.
And, most of all, making use of
the new features in Xcode 10 to
define custom color and image
assets specifically for Dark
Mode.
Now, if you need a review on any
of those topics, I highly
recommend going back and
watching the intro session on
video later.
Now, most UI will look great in
Dark Mode using just those
techniques.
In fact, some of our system apps
required no other changes.
It was great.
But we know some cases will
require a little bit more work
and that's what we're going to
get into in this session.
We're going to cover six main
areas today.
First, the appearance system,
how it works, and how you can
make use of it in your custom
views.
Second, materials, what they
are, and how you can best make
use of them in your UI.
Then I'll hand it over to Jeff
and he'll talk about vibrant
blending, which is an awesome
way to make your views look
great.
As well as reacting correctly to
selection using something called
background style.
Finally, he'll wrap it up with
some discussion on how to back
deploy your app to older
versions of macOS while still
supporting Dark Mode, as well as
some general tips and tricks for
polishing your apps for Dark
Mode.
All right.
Let's get started.
So, in Mojave, your app will
need to look great in light and
dark.
And the way you'll do that is
using something called
NSAppearance.
NSAppearance is the theme system
used throughout Cocoa and the
key part about it is you only
have to maintain a single view
hierarchy and NSAppearance will
help it look great in light and
dark.
Now, in addition to being at the
core of Dark Mode, we've already
been using NSAppearance for
several years and it's underlied
[phonetic] such features as the
high contrast mode of macOS as
well as the touch bar UI
designed specifically for that
awesome piece of hardware.
Now, previously we've had one
main appearance, one main light
appearance for aqua windows and
we called aqua.
And, of course, in 10.14, we're
introducing a second appearance
for aqua windows for Dark Mode
called darkAqua.
These objects contain all the
assets that views draw with.
So, any time you use system
dynamic colors or standard
effects or named images or even
just standard Cocoa controls,
this is where all that stuff is
coming from.
And AppKit will automatically
provide appearances for all of
you views and windows based on
the user's light/dark preference
in system preferences once you
link on the macOS 10.14 SDK.
So, here's our beautiful
Chameleon Wrangler app that
Rachel and Taylor created in the
intro session and you can see
once we linked it on the macOS
10.14 SDK, AppKit went ahead and
automatically gave it the
darkAqua appearance.
Now, that's great, but what if
we want to change the
appearance?
For example, what if we wanted
to change the appearance of this
notes view?
We might think that in the dark
appearance we still might want
the notes view to appear light.
Well, you can do that using
something called
NSAppearanceCustomization.
Now, this is a protocol, but
it's not a protocol you have to
go off and adopt in your
applications.
It's already adopted by NSView
and NSWindow and, in Mojave,
NSApplication conforms as well.
It's a pretty simple protocol.
It just adds two properties.
First property is appearance and
this is where you can override
the appearance for a particular
object.
Now, it's an optional
NSAppearance because, if you set
it to nil, the object will
simply inherit its appearance
from its ancestors.
There's also effective
appearance and this is a
read-only property that you can
use to find out what appearance
a view will draw with.
And of course, to use this,
you'll have to get the right
NSAppearance object and you can
do that pretty easily using the
NSAppearance named initializer.
Just pass aqua or darkAqua based
on which appearance you want and
then you can go ahead and just
assign that to the appearance
property of the object that
you'd like to customize.
So, in this case, we'll assign
the aqua appearance to the
appearance property of the text
view and now it uses the light
appearance.
All right.
That was pretty easy, so let's
take a look at another case.
You might have a window that
kind of hangs off of a
particular view.
And you probably want its
appearance to match the view it
hangs off of.
Now, we could just assign the
aqua appearance to this window
just like we did to the view,
but what we really want is
something a little stronger.
We want its appearance to
inherit from the view and we can
do that-- first of all, AppKit
will automatically do this for
us for a number of common
windows, like menus, popovers,
tool tips, and sheets, so you
don't have to worry about it in
those cases.
But, for custom cases like this,
there's new API in Mojave that
you can use to do this.
It's called Appearance Source.
Now, this is a property that
takes any object that conforms
to that
NSAppearanceCustomization
protocol-- so, views and
windows-- and you just assign it
to the appearanceSource property
and the window will inherit its
appearance from that object.
So, in this case, we'll assign
the text view to the
appearanceSource property of
that child window and now it's
appearance will always inherit
from that view no matter what it
is.
In fact, you should think of the
appearance system as a sort of
hierarchy.
Similar to the view hierarchy
you're probably familiar with,
but extending to windows and the
application as well.
And when we ask AppKit for a
view's effective appearance,
AppKit will simply walk up this
hierarchy until it finds an
object with a specified
appearance and that's the
appearance we'll use.
OK.
So, now that we know how objects
get an appearance and how the
appearance system works, let's
talk about how you can use it in
your custom views and controls.
Here's an example.
Let's say I wanted this custom
header view here to use a
different color in light and
dark appearance.
Now, we already know in Xcode 10
I can go into the asset catalog
editor and specify specific
color assets for light and dark.
But then how do I use that in my
custom view?
Well, here's one way that seems
tempting but won't work and I'll
show you why.
First, we'll add an NSColor
property to our view.
And in init, we'll use that
color to populate our layer.
And if the color changes, we'll
go ahead and update our layer
there too.
Let's try that out.
OK. It looks pretty good in
light, but if we switch to dark,
we can see our color didn't
actually change.
And that's because even though
our NSColor is dynamic, the CG
color that we get from it is
static.
It won't change for the
appearance.
And, since we configured our
layer in our initializer, we
didn't get a chance to run any
code when the appearance
changed.
Now, the key takeaway from this
is you need to do your
appearance sensitive work in
specific areas.
Specifically, the update
constraints, layout, draw, and
update layer methods of NSView.
Now, AppKit will automatically
call these methods as needed
when the appearance changes.
And if you need to trigger them
manually, of course you can
always use the
needsUpdateConstraints,
needsLayout, and
needsDisplayProperties and
AppKit will automatically call
them.
So, let's go back to our
example.
Instead of overriding init,
we'll implement updateLayer and
there we can go ahead and safely
populate our layer by asking our
NSColor for a CG color.
And if our color changes,
instead of updating our layer
right there, we'll just set the
needsDisplay property to true.
AppKit will come back around
automatically and call
updateLayer.
So, let's run it again.
Still looks good in light.
And now it uses the correct
color in dark just like we
wanted, so that's great.
Now, what if we want to do
something a little more
complicated that might not be
expressible just with dynamic
colors or images?
For example, maybe I would like
to add this nice white glow
behind Chloe's beautiful face
here, but only in Dark Mode.
How would I do that?
Well, for cases like that, we
have new API in Mojave that you
can use to match against your
view's appearance.
Let me show you how it works.
So, in this view, I'll override
the layout method and I'll
switch on effectiveAppearance
bestMatch(from:, I'll pass an
array with all of the appearance
names that my view happens to
know about.
In this case, aqua and darkAqua.
Then it's just a matter of
implementing behavior for each
of those appearances.
So, for the aqua appearance,
I'll simply use my imageView
with Chloe's face as a subview.
And for darkAqua, I'll not only
use that imageView, but I'll
also through my glowView behind
it.
Finally, I'll implement a
default case and this is for
appearances my view doesn't know
about and that includes
potential appearances Apple
might come out with in the
future.
OK.
Let's take a look at what it
looks like.
So, there it is in light, no
glow, that's what we wanted.
Switch to dark and we have that
glow.
That's great.
All right.
Let's talk for a minute about
high contrast.
So, I said before that we've
been using NSAppearance for the
high contrast mode of macOS.
And one of the nice side effects
of doing all this work to
support Dark Mode is it makes it
really easy to support high
contrast really well as well.
As a reminder, high contrast is
enabled through the increase
contrast checkbox in system
preferences.
And in this mode, colors are
changed so that control bounds
and other kinds of boundaries
are more easy to see.
Now, in this mode, AppKit
automatically replaces the aqua
and darkAqua appearances with
high contrast counterparts.
Now, these high contrast
appearances inherit from their
normal contrast versions.
So, what that means is any code
you've written to take advantage
of Dark Mode will automatically
apply in high contrast Dark
Mode.
But you can go even further.
In Xcode 10, if you check this
high contrast checkbox in the
asset catalog editor, it'll
allow you to specify color and
image assets specifically for
the high contrast versions of
the appearances.
Now, you can also use those
appearance names in code.
You might be temped to think,
well, great, I'll just pass them
to NSAppearance themed and I'll
get the NSAppearance object and
I'll do something with that, but
that won't work.
Those appearances are only
available through system
preferences.
But what you can do is pass them
to bestMatch(from:) just like we
did before for Dark Mode to
implement custom programmatic
behavior.
OK.
Let's talk for a minute about
sublayers.
I know a lot of you out there
have views that manage their own
sublayers and there are
important things to be aware of
for Dark Mode.
Primarily, you need to know that
custom sublayers will not
inherit your view's appearance
automatically.
Now, the easiest fix for this is
to switch them from being
sublayers to subviews.
If you do that, AppKit will
automatically handle the
appearance inheritance for those
views, just like any other view.
Otherwise, you'll have to manage
those layers manually using a
couple techniques that I'll talk
about now, viewDidChange
EffectiveAppearance and the
concept of the current
appearance.
So, first viewDidChange
EffectiveAppearance.
This is a new method on NSView
that you can override to find
out when your view's effective
appearance changes.
Now, this is a good time to
perform any custom invalidation
you might need to do or drop any
caches that are no longer
relevant.
But remember you don't need to
invalidate the view itself here,
AppKit will do that for you
automatically.
Second, the concept of the
current appearance.
Now, this is a thread local
variable that you can access
through a class property on
NSAppearance.
If you're familiar with concepts
like the current NSGraphics
context or the current
NSProgress, you already know
what I'm talking about.
If not, just remember that this
is the appearance used to
resolve dynamic colors and
images.
AppKit will set up the current
appearance automatically for you
before we call any of those
special NSView methods we talked
about before, like
updateConstraints, layout, draw,
and updateLayer, but you can
also set it up yourself where
necessary and let's take a look
at an example why you might do
that.
So, here's a custom that
maintains some sublayers.
I'll override this new
viewDidChange
EffectiveAppearance method and
I'll set my sublayer
needsDisplay.
Now, if I didn't do this, my
sublayer wouldn't update when my
view's effective appearance
changed.
It would just stay the same.
And then in my layer delegate
routine, I'll save off the
current appearance for later and
then I'll go ahead and set the
current appearance to my view's
effective appearance.
Then I can go ahead and update
my layer.
Now, if I hadn't set the current
appearance before this, this
code wouldn't be using my view's
appearance and so it would end
up looking wrong.
Finally, when I'm done, I'll
just restore the old current
appearance.
Here's another thing to be aware
of if you're managing layers.
You might have code that looks
like one of these two examples.
Either you're setting the
contents of a layer to an
NSImage or you're using the
layer contents for content scale
API to create layer contents
from an image for your layer.
If you have code like this, you
should know that the image will
not automatically inherit the
appearance.
As before, the best fix is to
switch to views.
In this case, NSImageView.
NSImageView will take care of
this detail as well as a bunch
of others automatically, so do
that if you can.
Otherwise, you'll need to create
a CGImage from your NSImage for
your layer.
And you'll do that using the
cgImage(forProposedRect:,
context:, hints: API on NSImage.
And you'll have to be careful to
do this at a point where the
current appearance is correct.
So, a good place to do it is in
your updateLayer method.
All right, so that's appearance.
Now let's talk about materials.
Now, you've probably heard that
materials are one of the
building blocks of the modern
Mac UI, but you may have
wondered to yourself, well, what
exactly is a material, so let's
start with a definition.
Materials are dynamic
backgrounds that make use of
effects like blurs, gradient,
tinting, translucency, and they
provide a sense of depth or
context to your UI, as well as
just a bit of added beauty.
Here's a pretty typical Mac
desktop and you can see all the
different places where we're
using these material effects--
actually, this isn't even all of
them.
Now, AppKit automatically
provides materials in a number
of common places, like the title
bars and backgrounds of windows,
table views, sidebars, popovers,
menus, and even other places as
well.
But you can create a material
yourself and add it to your UI
using a view called
NSVisualEffectView.
If you're not familiar with
NSVisualEffectView, quite
simply, it's a view that shows a
material.
And if you want to use one,
you'll need to be aware of three
main properties that you'll have
to set up and I'll go through
these in order.
The state, blendingMode, and
material properties.
So, first, the state property.
This controls whether the
material uses the active window
look.
Now, by default, the material
will just match its containing
window and so when that window
is active it'll look active.
When the window's inactive, the
material will look inactive.
But you can also specify this
specifically to be active or
inactive if you'd like to
control it manually.
Second, the blendingMode
property.
This property controls whether
the material punches through the
back of the window.
Let me show you what I mean by
that.
Here's a preview using two
different materials.
For one, this title bar
material, if we peel it back, we
can see that it's blending the
contents within the window,
including that color image
there.
So, it's not punching through
the back of the window.
There's also the sidebar
material and if we peel it back
we can see it's blurring the
contents behind the window, so
it's punching through the back
so it can see to the windows
behind it as well as the
desktop.
So, by default, a visual effect
view will be in behind window
mode, but you can control that
using the blendingMode property.
Finally, the material property.
This property encapsulates the
material effect definition.
What do I mean by that?
That means the exact recipe of
blur, translucency, gradience,
tinting-- that all depends on
the material property.
Now, when we first started using
materials in Yosemite, we had
two main materials, the light
and dark materials, and those
served us really well at the
time, but since then we've
really expanded our use of
materials across the system.
And now with Dark Mode, it no
longer really makes sense to
specify a material just as light
or dark.
Instead, we have something
called semantic materials.
Now, if you're familiar with
semantic colors, you know that
they're named after where
they're used, not necessarily
what they look like.
Same thing for semantic
materials.
The menu material, for example,
will always look like system
contextual menus, regardless of
light versus dark.
And in Mojave, we're introducing
a bunch more semantic materials
so that you can always use the
right one for your specific use
case.
In fact, these semantic
materials are now our preferred
way of using materials and we're
deprecating these non-semantic
materials like light, dark,
medium light, and ultra dark.
If you're using one of these
materials, now is a great time
to go ahead and switch over to a
semantic material that's right
for your use case.
Just to give you an idea of
where we're using these semantic
materials across the system,
here's the Finder using the
title bar and sidebar materials.
Here's Mail using the header
view and content background
materials.
Here's our Chameleon Wrangler
app using the
underPageBackground material.
And here's system preferences
using the window background
material.
Now, of course this window
background material, as you've
probably heard, is one of these
special desktop-tinted materials
new in Mojave.
And the way these work is they
pick up a slight tint from the
desktop picture based on the
window's location onscreen.
And the idea here is to help
your window blend in with the
windows on the rest of the
system.
Again, the easiest way to get
one of these desktop-tinted
materials is to use the
automatic support in NSWindow,
NSScrollView, NSTableView, and
NSCollectionView.
The default configurations of
these objects will come with
this desktop-tinted effect.
You can also configure NSBox to
get these materials by setting
its type to custom and selecting
one of these fill colors.
It'll use the corresponding
NSVisualEffectView material.
Here's an example.
I'll set my box's type to custom
and then I'll set its fillColor
to the underPageBackgroundColor.
Of course, I can also use
NSVisualEffectView, I can set
it's material property to the
underPageBackground material.
Now, the advantage of using
NSBox is it's back-deployable
actually all the way back to
Leopard.
VisualEffectView, on the other
hand, gives you a little more
flexibility and I'll give you an
example of that later.
So, just as a reminder, these
materials will show their
untinted color in light.
And in dark, they'll show that
desktop-tinting effect.
But remember that the tint
effect can be disabled.
Let me show you why.
So, in Mojave, you can choose an
accent color for the system.
And if I switch this over to
graphite, you'll probably first
notice that all the controls
lost their colored accents, but
those desktop-tinted materials
also lost their tint.
So, just make sure you're not
depending on that tint being
there in any way.
Now, VisualEffectView by default
will show its material in its
frame rectangle like this.
And that's pretty great, but
what if I wanted to show a
custom UI element with this
material, like say a chat
bubble.
How would I do that?
Well, here's one way that seems
tempting, but won't work, and
I'll show you why.
We'll first implement the draw
method on NSView and then I'll
go get my custom chat bubble
BezierPath.
And then I'll fill with the
controlBackgroundColor in that
path.
Now, if you do that, you'll find
it looks something like this and
it looks pretty good, but if we
zoom in closely, you'll see that
the bubbles are not getting that
desktop-tinting effect that we
want.
It's just a plain gray.
So, what went wrong?
Well, this effect is provided by
the Quartz window server like a
lot of our other material
effects.
And what this means is it
updates asynchronously from your
application and this is great
for performance, but it also
means that you can't directly
draw with that color or get it's
RGB values.
Instead, you can use the
maskImage property of
VisualEffectView to do something
very similar.
maskImage is an optional NSImage
on VisualEffectView that
VisualEffectView will use to
mask its material, the material
that it shows.
And in addition to using
standard art-based images, you
can use drawing handler images
to simulate drawing with the
material.
Let me show you an example.
So, I'll go back to my view,
I'll override layout, and I'll
go ahead and add a
VisualEffectView.
I'll set its material to the
contentBackground material, and
then I'll create a drawing
handler image using the NSImage
size flipped initializer that
takes a block.
In it, I'll set the white
color-- this color doesn't
really matter as long as its
opaque.
And then I'll go ahead and fill
with my path.
Then I'll set that image ask the
maskImage on my
VisualEffectView.
All right.
Let's look at it now.
Looks a lot better.
It's desktop-tinted.
And, if we look side by side, we
can really see the difference.
So, this technique works with
any material, but just remember
that only the alpha channel of
the image is used for the mask.
This is similar to template
images.
And the mask only masks the
material, not any subviews or
other descendent views of the
VisualEffectView.
A common technique is to provide
a resizable image for this-- for
the maskImage using the
capInsets and resizingMode
properties of NSImage.
And this is really good for
performance.
OK.
With that, I'll hand it off to
Jeff, who is going to talk about
vibrant blending.
[ Applause ]
Jeff.
>> All right.
Thank you, Matt.
So, now that we've had a look at
our great materials, I want to
cover the things that we draw in
front of those materials,
particularly the materials that
we use that pull in part of the
background and provide that
really awesome blur effect.
So, if we revisit our Chameleon
Wrangler application, we have
this UI here, it's our
mood-o-meter.
It's where we go to record how
our various reptiles are
feeling.
And it's in a popover, which
means that it's automatically
getting that awesome popover
material backing.
And what we want when we're
drawing over this backing
material is for our content to
really stand out on top of that
varied background.
Something like this.
And we do that with an effect
that we call vibrancy.
So, what is vibrancy?
It's a blending mode that we
apply to the content that
uniformly lightens or darkens
the content behind it.
It's very similar to a color
dodge or burn that you might
have seen in your favorite photo
editor or design tool.
But let's take a closer look.
Here we have a glyph that's
drawing in about a medium gray,
about a 50% gray, but at 100%
opacity.
And when we apply the vibrant
blending effect that we use
against dark materials, which we
call a lightening effect, we can
see that it's not that the
opacity has dropped on our
glyph, but we're actually
lightening the content behind it
using the lightness of that gray
value.
And in fact, when we look at how
this works on a range of gray
values-- here we have swatches
going from 0% to 100% gray, all
totally opaque.
When we apply our lightening
effect, we can see a number of
interesting things have
happened.
Down on the bottom right side,
we have 100% light, and because
we have added the lightness of
white to the content behind, it
just remains white.
There is nowhere further to go.
But on the top left where we
were drawing black, there was no
lightness to add, which means
that it completely disappears.
In fact, you wouldn't be able to
see it if I didn't have an
outline there.
And in-between we can see that
we have varying degrees of
lightening which we can use to
establish a hierarchy of content
in our application.
But where does this effect come
from?
Well, it's our old friend
NSAppearance, it turns out.
We have two special vibrant
NSAppearance objects,
vibrantDark and vibrantLight and
these are a complete package.
Not only do they include the
exact formula that we use for
that lightening or darkening
effect, but they also have a set
of control artwork and color
definitions that have been
designed to work great with that
blend mode.
But how does your code use it?
Well, it's very simple.
In your NSView subclass, you can
override the allowsVibrancy
property to return true and the
blending effect is going to
automatically apply to your
views drawing and also the
drawing of all of its
descendants.
Typically, when you're drawing
in this vibrant context, you
want to use one of the built-in
label colors, depending on the
prominence of your content.
Both vibrantDark and
vibrantLight have great
definitions for all four of
these colors that allow you to
establish that nice hierarchy.
However, you don't have to use
these colors.
You can use any color that you'd
like, but we prefer to use
non-grayscale colors.
Avoid non-grayscale colors
because, if you use them, the
blending effect is going to
impact the design intent of your
color and it's going to wash it
out in a way that is not
desirable.
I'll show you an example of that
later.
So, revisiting our application,
we can go ahead and override
allowsVibrancy on our view and
in this case we're going to just
set it on the view that contains
our entire meter in the entire
popover.
And let's see what that looks
like.
Well, our slider looks pretty
good.
It's exactly what we expected.
But what happened to the faces?
They're all washed out.
And what happened here is that
when we set allowsVibrancy on
the overall meter view, not only
are we getting the vibrant
blending on that view, but also
both of these subviews.
And the fix here is pretty
simple.
If we localize our definition of
allowsVibrancy to just the part
that's drawing the slider, we
get exactly what we expected.
Our slider is drawing vibrantly
and the colors in our face
buttons look exactly the way
that we wanted.
When you're drawing vibrantly,
typically you'd want to apply
vibrancy to only the leaf views
that are drawing the content
that you actually want to have
vibrant.
And, if you have views that are
drawing a mix of content, that
means that you probably want to
break your drawing out into
separate sibling views that you
can use to apply vibrancy at the
granularity that you want.
Further, you should avoid
overlapping vibrant and
non-vibrant views.
If you do this, the blending
modes can clash and you might
find that some of your content
is drawing with a blend mode
that it didn't expect.
Further, don't subclass Cocoa
controls just to override
allowsVibrancy.
I mentioned earlier that the
vibrantLight and vibrantDark
appearances have been designed
with control artwork and colors
that were designed specially for
the blend mode and if you remove
that blend mode, the contrast on
that artwork is not going to be
what you expected because we're
using the blend mode to provide
a lot of that pop against the
material, so you should only
override allows vibrancy if
you're actually overriding
drawing and you know what
vibrant blend mode or
non-vibrant blend mode is
appropriate for the drawing that
you're doing.
That's vibrancy.
Next, I want to talk a little
bit about background styles,
specifically the ones that we
use for selections.
So, here we have a pretty
typical situation in a aqua
Cocoa application.
In this case, it's a message
from the Mail application and we
can see that when we have a
selection state, we need our
content inside of this table row
to invert to look good against
that blue selection.
But when we add darkAqua into
the mix, we can see that we
can't just naively invert our
content anymore.
That's not going to work
uniformly.
And so we need to describe these
states semantically.
Now, if you're familiar with
Cocoa, you've probably seen the
NSView.BackgroundStyle enum and
that includes a couple of cases,
including light and dark, and
NSTableView sets this
automatically on the
TableRowView, TableCellView, and
also all of the controls that
are immediate subviews of your
TableCellView.
Now, traditionally, we have set
the light background style on
unselected rows and the dark
background style on selected
ones.
But, in the face of this
brand-new, beautiful theme where
the background is effectively
always dark, these names don't
make sense anymore and so we've
renamed them to normal and
emphasized, respectively.
And these are just more semantic
descriptions that better match
the way that these enum cases
are used in a modern Cocoa
application.
We also have some additional
updates with background styles,
including that TableView will
now automatically set that
background style recursively on
all of the controls in your
table row, not just the ones
that are immediate subviews of
your CellView.
And so, if you've been catching
that background style and trying
to forward it along to all these
subviews because you wanted to
use a stacked view or something
for layout, you no longer have
to do that on Mojave.
That's the applause of somebody
who's done this manually.
Thank you, I agree.
Further, all four of our label
colors now automatically adapt
to the background style, which
means that you can just set up
your content hierarchy once,
describe it semantically, and
it's going to look great in both
of these contexts.
You can also use these
emphasized variants manually and
I'll give you an example.
So, here we have something that
looks a little bit like the icon
view in Finder.
And we've got two labels that
are ascribed with label color
and secondary label color.
And we want to draw a custom
selection behind them, so we've
got this custom Bezier
path-based selection, maybe
we're filling it with alternate
selected control color, and we
want our labels to match the
primary and secondary variants
in this emphasized style.
And to get that is very simple.
All we have to do is set the
background style to emphasized
on both of our text fields and
they're automatically going to
provide this nice emphasized
variant.
And the great thing is that now
that we've described it this
way, when we switch into Dark
Mode, everything just works.
We don't have to do anything
special to support that.
One final note on selections.
The selection material that you
commonly see in sidebars, menus,
and popovers now follows the
accent color preference on
Mojave.
And what that means is that if
you're drawing a custom blue
selection, it's not going to fit
in.
Instead, you should use
NSVisualEffectView.
It has a special selection
material just for this and when
you use this it's going to
automatically follow the
preference, as you expect.
Now, before I get into the
exciting part, the tips and the
tricks, I want to say a couple
of words about backward
deployment because we know that
many of you, especially on the
Mac, like to deploy your
applications back to previous
releases of macOS and it was
important to us to make sure
that you could adopt Dark Mode
without necessarily compromising
on your backward deployment.
And so I'm going to step through
a couple of APIs and just
examine them for backward
deployment, starting with system
colors.
So, here's a sampling of the
system colors that we support
that are dynamic for the
appearance.
And what I want to highlight
here is that the ones
highlighted in green have been
available since at least 10.10
Yosemite, many of them actually
far further back.
And that means that we think
that you have a great vocabulary
of colors available to you to
describe more or less any UI
that you'd like and that all
supports backward deployment out
of the box.
For custom colors, our modern
preferred solution for defining
them is asset catalogs and these
are available back to 10.13.
Now, when you do specify dark
variants for any of your assets,
when you back deploy them, those
dark variants are safely ignored
on previous versions of the
operating system, so that's a--
that's a solution that has
backward deployment built right
in.
But if you want to deploy back
further than 10.13, you can use
a technique like this where you
write a custom color property.
And here we just encapsulate the
availability check to use our
asset catalog color on operating
systems that support it and then
we can go ahead and put in a
hardcoded fallback color for
those older operating systems.
Desktop-tinted materials is
another great new thing in
Mojave and if you want to
address those materials directly
with VisualEffectView, of course
that's only available starting
in 10.14, but we've been
providing-- but we have classes
that are providing these
materials automatically,
including Window, ScrollView,
and TableView, which have been
available since essentially the
beginning of time.
In fact, some of these predate
macOS 10.0.
And so, if you configure them
correctly, they're going to on
previous operating systems show
that special NSColor which looks
exactly the way that you would
expect in previous versions and
then when you run it on Mojave
you're going to get that
material automatically.
And of course NSBox, the custom
style that allows you to set a
fill color, deploys back to
Leopard 10.5 and so does
NSCollectionView.
And this works whether you're
using the legacy
NSCollectionView API or the
modern one, although we'd prefer
that you use the modern one.
Finally, enabling Dark Mode is
generally gated on linking
against the 10.14 SDK, but, as
you can see, really, the tools
that you need to develop a great
Dark Mode application aren't
necessarily specific to the
10.14 SDK and you could have
developed one just using the
10.13 SDK that you have today.
And so, if you have a situation
where you can't necessarily
update your SDK, we have an
Info.plist key that you can use
to opt-in to Dark Mode.
It's called
NSRequiresAquaSystemAppearance
and if you set that to NO
explicitly, then that's going to
enable Dark Mode even if you're
linking on an earlier SDK,
although we very strongly prefer
that you update your SDK.
It's a far better solution.
You can also set this key to YES
to disable it temporarily-- and
I want to emphasize temporarily.
This is a key that you can use
to give yourself time to really
build a great polished update
for supporting Dark Mode.
Finally, some tips and tricks.
First of all, when you're
updating your application, one
of the greatest things that you
can do is just audit your use of
NSColor just by searching
through your code base and
seeing where you're using it.
And you're going to find a
couple situations that you can
use to upgrade to make your Dark
Mode experience a lot better.
And so, for example here, we can
find places where we're using
named colors that are not
dynamic and also colors that
have hardcoded components.
And when we encounter these
kinds of situations, we can look
at these and decide one of two
things.
One, maybe there is a built-in
system color that describes what
I'm going for and is fully
dynamic for the appearance.
Or, two, this is a custom color
that I think is really important
to be specific to my
application.
And so the first case is pretty
straightforward.
We were using black color for
this label and we can just
switch that to labelColor and
that's going to be fully dynamic
and do what we expect.
But in the second case, we might
decide that this color is
actually really special to our
app and that's a really great
candidate for moving into the
asset catalog.
Not only does this clean up our
code because we get all of these
magic numbers out of our code
and into a data-driven source,
but we can also then set a dark
variant for that color and so we
get great Dark Mode support
built in.
Another common source of issues
is offscreen drawing.
To do offscreen drawing, you
have to make sure that you're
being sensitive to the
appearance and also other
drawing conditions.
One really common case of this
is using the NSImage lockFocus
API to try and draw custom
NSImages.
In this case, we're going to go
ahead and try and draw this
badged image where we have a
base image and we're applying a
badge because something new is
happening with our lizard.
And, in this case, we're
creating an NSImage, calling
lockFocus on it, and then doing
our drawing.
And the problem with this is
that once we've used lockFocus,
we lose a lot of the semantics.
We just have a single bitmap
representation.
And so if the appearance changes
or if many other conditions
change, including say the
backing scale factor because
you've moved your window from a
Retina display to a non-Retina
display, suddenly this drawing
is going to be stale.
So, a better solution is to use
the block-based image-- image
initializer, NSImage size
flipped drawing handler.
And we can just do the exact
same drawing that we were doing
before, but inside of this
block.
And when you assign this kind of
image to an NSImageView, you're
automatically going to have this
block rerun when the appearance
changes, scale factor changes,
color gamut changes-- anything
changes, essentially.
And so that's great news because
if our, say, badge fill color is
a dynamic color, it's going to
always resolve against the
correct appearance.
There are a couple of other ways
that you might be doing
offscreen drawing.
You might be making custom
bitmap graphics contexts using
NSGraphicsContext or
CGBitmapContext.
And, depending on what you're
doing, these might also be great
candidates for replacing with a
block-based NSImage.
Further, if you're using the
NSView cacheDisplay in Rect
method to cache your image to a
bitmap rep, just be aware that
this method is not going to
capture some of our more
advanced rendering techniques
like materials and blurs and
it's also just another way that
you can produce drawing that
goes stale when the appearance
changes, so be aware of that.
Here's another situation that
you might find yourself running
into.
If you have an
NSAttributedString or
NSTextStorage and you're
manipulating those attributes
manually-- say I am in this
case, I've just set my
attributes to just be a
dictionary with a font in it--
you might find that this
happens.
Your text is drawing black even
when you switch into Dark Mode
and what has happened here?
Well, we're missing a foreground
color attribute and when the
text drawing engine encounters a
range of attributed strings that
doesn't have a foreground
attribute, it defaults to black.
And this is what it has always
defaulted to and it's going to
continue to be the default for
compatibility.
So, one way to fix this is to
set a foreground color
explicitly to one of our dynamic
system colors, and that's going
to do what you expect.
But a better alternative is that
if you're doing manual
attributed string drawing, you
should switch to a Cocoa
control, like an NSTextField,
which does this for you
automatically, or, if you're
manipulating the storage of a
textView, we have new API called
performValidatedReplacement on
textView that does a nice thing
for you.
If you go ahead and replace a
string with an attributed string
in your textView, it will fill
in any missing attributes with
the typing attributes from the
textView, so that way you can go
ahead and specify your new
attributed string without having
to manually merge all your
attributes together.
Here's something else that we've
encountered in a couple places,
which is appearances that are
set in Interface Builder.
So, if you're going ahead and
building and debugging your
application and you find that
there's some part of your app
that just isn't switching, you
might have this in your
Interface Builder.
A hardcoded aqua appearance.
And it's easy to miss, because
before today, essentially, you
were always running under aqua,
so you didn't notice it.
And the fix for this is easy.
If you set this back to the
Inherited option in the pop-up
menu, your view's going to
automatically inherit from its
ancestor.
An extra special case of this is
NSVisualEffectView.
It's very likely that if you
have a VisualEffectView in
Interface Builder or even in
code, you're setting one of the
two vibrant appearances on it
and the great news is that in
macOS 10.14 this is no longer
necessary.
NSVisualEffectView will
automatically pick the right
vibrant appearance based on the
appearance it's inheriting.
So, if it inherits darkAqua,
it's going to choose vibrantDark
and if it inherits aqua, it'll
choose vibrantLight.
And so the fix for this is easy.
In Interface builder, you can
set this to inherited and then
in code you can set the
appearance to nil or just delete
your override.
Interface-- speaking of
Interface Builder, Interface
Builder is a great tool for
designing and previewing your
views visually.
And so, for example, here I have
a view that is actually a custom
view using IB designable.
So, I'm rendering a gradient
here and I can see it right here
in the canvas.
And, by default, my canvas is
previewing my custom designable
view using the canvas's
appearance, in this case dark.
But down at the bottom, we have
a new toggle that lets you go
ahead and set it to the light
appearance so that you can
preview the way that your view
looks in either appearance.
And thanks to Interface
Builder's great support for
asset catalog colors, we can
actually use our custom asset
catalog colors, which have dark
and light variants, and we can
preview them in the canvas live.
And if you see there's a little
arrow button built into that
pop-up button and you can use
that to follow it and go
straight to the definition in
your asset catalog, so you can
see live as you're changing it.
And you can do this all without
even building and recompiling.
When you do build and run,
you're going to see a new item
in your Debug Bar and it
produces a menu that allows you
to choose the appearance for
your application.
And this is really handy for
previewing your app in various
appearances without having to go
and reconfigure your entire
system.
Not only can you choose light
and dark, but you can also
choose the high contrast
variants and test those as well.
And, if you have a Touch Bar
Mac, this appears in the
expanded Debug Bar as well, so
you can do this without even
leaving your app to go back to
Xcode.
Finally, I want to talk about
one last tool in Xcode that is
really great for debugging your
Dark Mode applications.
So, here we have our app and
really things are looking pretty
good.
There's nothing out of place,
but I find that when I scroll
and rubber band a bit, oh, I'm
revealing something that I
didn't expect.
There's a light background
hiding back there somewhere, but
it's hard to see without doing
that little scroll gesture.
And this is a great case for
using the View Debugger.
Using the View Debugger's
expanded 3D view, the view
that's drawing unexpectedly is
really easy to spot.
And in this case, we can see
that although our collection
view was drawing the background
that we expected, the scroll
view behind it still has a light
background for some reason.
And when we select it, we can
use the Inspector to see how
it's being configured.
And in this case, we can verify
that, yeah, it's just drawing a
hardcoded white color and that's
a really easy fix.
The View Debugger has made a
number of enhancements in Xcode
10 that are great for debugging
Dark Mode applications,
including colors.
They can now show you the names
of colors, both dynamic system
colors and your asset catalog
colors, so you can identify
where these RGB components are
coming from, and it'll show you
the configuration of your view
for NSAppearance, including the
appearance that it's going to
draw with as well as whether
there's any local overrides of
NSAppearance on that object.
So, we have covered an awful lot
of content and so let's rewind
and make sure that we remember
it all.
We started off with NSAppearance
and leveraging it effectively to
draw your custom views that
adapt based on the theme.
Then we learned how to add depth
and beauty to our UI using our
new and updated palette of
NSVisualEffectView materials.
We talked about drawing in a
couple of interesting contexts,
both vibrancy and selections,
and then we walked through some
of the great ways that Xcode can
help you design and debug your
Dark Mode applications.
As always, you can go to
developer.apple.com to re-watch
the video for this talk and see
any related resources and we
have labs today.
We have a special Cocoa and Dark
Mode Lab, it's at 2:00, and not
only will we have Cocoa
engineers onsite to help you
with your code, but we'll also
have human interface designers
onsite to help you with your
design questions as well.
So, go get lunch, think about
Dark Mode the entire time, and
then come see us.
And then, finally, we have an
additional Cocoa Lab on Friday
at 11:00 as well.
All right.
Thank you very much.
[ Applause ]