- (DiggObject *)fetchStoryWithID:(int)ID;
- (DiggObject *)fetchStoryWithTitle:(NSString *)name;
- (DiggObject *)fetchStoryWithURL:(NSString *)url;
- (NSMutableArray *)fetchStoriesForDomain:(NSString *)domain;
- (NSMutableArray *)fetchStoriesForTopic:(NSString *)topic;
- (NSMutableArray *)fetchStoriesForContainer:(NSString *)container;
- (NSMutableArray *)fetchStoriesSubmittedBy:(NSString *)user;
- (NSMutableArray *)fetchPopular;
- (NSMutableArray *)fetchRecent;
- (NSMutableArray *)fetchStories;
- (NSMutableArray *)fetchUpcoming;

It’s also just as easy to set the options or parameters that you would like to call the query with:

-(void)setAppkey:(NSString *)newAppkey;
-(NSString *)appkey;

-(NSString *)proxy;
-(void)setProxy:(NSString *)newProxy;

-(BOOL)single;
-(void)setSingle:(BOOL)newSingle;

-(int)count;
-(void)setCount:(int)newCount;

-(int)offset;
-(void)setOffset:(int)newOffset;

-(int)total;

-(NSString *)domain;
-(void)setDomain:(NSString *)newDomain;

-(NSString *)sortBy;
-(void)setSortBy:(NSString *)newSort;

-(NSString *)status;
- (void)setStatus:(NSString *)newStatus;

- (NSString *)minSubmitDate;
- (void)setMinSubmitDate:(NSString *)newMinSubmitDate;

- (NSString *)maxSubmitDate;
- (void)setMaxSubmitDate:(NSString *)newMaxSubmitDate;

- (NSString *)minPromoteDate;
- (void)setMinPromoteDate:(NSString *)newMinPromoteDate;

- (NSString *)maxPromoteDate;
- (void)setMaxPromoteDate:(NSString *)newMaxPromoteDate;

Currently the focus is on fetching stories, but fetching information for users, events (Diggs and comments), topics and containers will be written in shortly.

The only major thing lacking now is people to use the framework!

If you’re interested, drop a comment below and I’ll provide you with the necessary ammunition to create, fetch, parse and utilize Digg API calls with the ease of regular Objective-C Cocoa methods.

The official release date will depend on the response from the initial testers, so what are you waiting for? Ask me for a copy!

A sub-project of Shiira is a HUD-type window class. While they’re not completely accurate to the specifications used by Apple, these are probably the best HUD windows I’ve seen from a third party developer by a long shot.

The HUD Windows have the funny name of HMBLBlkAppKit. The Shiira team has really done a great job!

There have been attempts at figuring out the usage of the still-unreleased Digg API. However, Digg are yet to release their official API.

The staff at Digg were very kind in letting certain people have a play with the API before its release, and it’s looking to be, to put it bluntly, quite excellent. A lot of Digg plugins and services are going to be either made obsolete, or very happy with all the new possibilities that will be… well, possible!¹

For example, Lorelle talks about keeping track of your Dugg posts by subscribing to the search results RSS. This is only possible if you search for the past 7 or 30 days, and it doesn’t give you much information about the status, comments or diggs received on your posts. With the Digg API, this’ll be figuratively (because too many people use the word ‘literally’ figuratively) a breeze.

API’s are important, because they give people the opportunity to extend and use an application or service in a way that they like. A world without API is like Xcode without Cocoa or Carbon, or like the Mac without Applescript. An API helps to let the user do what they like, and it’s fun!

So web developers, start your engines for the Digg API…

Google & Cocoa

It may be API week or something, because Google have also conjured up an open source API for Mac developers to use Google data. The Google Data APIs Objective-C Library is a framework² that enables the use of Google data API’s within Objective C.

Greg Robbins posted some examples of this API at the Google Mac blog. Currently you can work with Google Calendar, Google Base, Google Spreadsheets and access to more services is in development. It seems to be a very nice framework, and I’m looking forward to seeing third party use of this.

That seems to round off API week. Any thoughts?

The framework (in more ways than one) for our smoking window is the Smoke framework embedded inside the Disco app. In your Xcode project, you can reference the framework straight from within the application. You’ll have to press Cmd-Shift-G and type in the path as you can’t navigate into bundles using the standard open file dialog. Normally the location is “/Applications/Disco.app/Frameworks/” inside which is the Smoke.framework bundle which we’re interested in.

Alternatively, you can copy the framework to /Library/Frameworks/ and reference it from there. If you need to modify the framework (more on that later) it’s best to choose this option so you leave the contents of the Disco application alone.

Head to the headers

Before we can use the framework, we need to have a valid header or header files for the framework, which tell Xcode (and us) mainly about the classes and methods in Smoke.framework. The headers aren’t included in the framework anymore, but to generate a header file is a simple matter of using a utility like class-dump on the framework.

Download Smoke.h:

You can take a look inside the header and see a bit of what’s possible with the framework. When you’re ready, we’ll move onto the…

Setup

Now we’ve got the framework and header in place, we need to code to actually get a window to smoke. On the surface, this is astonishingly simple.

In your Xcode project, make sure you’ve added Smoke.framework and Smoke.h as well as Quartz.framework as the smoke needs to use this. Now create a new Objective-C subclass. In this example we’ve used an NSWindow subclass, but you could just as easily subclass NSObject and only apply smoke on selected outlets. If you really wanted to start a bonfire, you could add a category to NSWindow just for smoking!

Firstly, we define everything in our header file. Our class is called SmokingWindow (SmokeWindow is taken by Smoke.framework) and we have four methods.

The header file will look something like this:

//
//  SmokingWindow.h
//  Smoke
//
//  Created by Ankur Kothari on 13/04/07.
//  Copyright 2007 Vacuous Virtuoso. All rights reserved.
//

#import <Cocoa/Cocoa.h>
#import <Quartz/Quartz.h>
#import "Smoke.h"

@interface SmokingWindow : NSWindow {
    SmokeController *theSmokeController;
    int smoking;
}
-(int)smoking;
-(IBAction)startSmoking:(id)sender;
-(IBAction)stopSmoking:(id)sender;
-(IBAction)toggleSmoke:(id)sender;
@end

• -smoking returns whether (1) or not (0) the window is currently smoking. It’s not needed to smoke, but it’s good practice.
• -startSmoking obviously starts the window smoking, and
• -stopSmoking stop the window smoking
• -toggleSmoke will stop the window smoking if it is, or start it smoking if it isn’t.

We’re storing the current state of the window for use by the -smoking method in the int smoking, and theSmokeController is a pointer to a SmokeController which will be doing most of the work.

Ok, now to the implementation.

//
//  SmokingWindow.m
//  Smoke
//
//  Created by Ankur Kothari on 13/04/07.
//  Copyright 2007 Vacuous Virtuoso. All rights reserved.
//

#import "SmokingWindow.h"


@implementation SmokingWindow

-(void)awakeFromNib
{
    SmokeCapabilities *smokeCapabilities = [SmokeCapabilities sharedCapabilities];
    theSmokeController = [[SmokeController alloc] init];
    [theSmokeController doExpensiveThreadedInitializations];
    [theSmokeController setSmokeAlgorithm:[smokeCapabilities smokeAlgorithm]];
    [theSmokeController attachToWindow:self];
    smoking = 0;
    [theSmokeController showWindow:self];
}

-(IBAction)toggleSmoke:(id)sender{
    if(smoking){
        [self stopSmoking:sender];
    } else {
        [self startSmoking:sender];
    }
}

-(IBAction)startSmoking:(id)sender
{
    if(!smoking){
        [theSmokeController startSmoking:self];
        smoking = 1;
    }
}

-(IBAction)stopSmoking:(id)sender
{
    if(smoking){
        [theSmokeController stopSmoking:self];
        smoking = 0;
    }
}

-(int)smoking{
    return smoking;
}
@end

The first few lines in -awakeFormNib get the SmokeController do some initialization.

SmokeCapabilities *smokeCapabilities = [SmokeCapabilities sharedCapabilities];
theSmokeController = [[SmokeController alloc] init];
[theSmokeController doExpensiveThreadedInitializations];
[theSmokeController setSmokeAlgorithm:[smokeCapabilities smokeAlgorithm]];

To tell the SmokeController which window to ‘burn’, the -attachToWindow: method is used. Since we’re using an NSWindow subclass in this example, we can just set it to self, otherwise you’ll need a pointer or outlet to an instance of NSWindow.

[theSmokeController attachToWindow:self];

To just make extra sure that the position of the smoke wont be offset if the window is dragged around during initialization, we call the -showWindow method. This isn’t completely necessary.

[theSmokeController showWindow:self];

To heat or cool the window, theSmokeController responds to -startSmoking and -stopSmoking. Easy enough!

More fun!

For extra smoking fun, you can add bindings to your application to control many aspects of the smoke. You can adjust the initial temperature, the amount of pressure exerted by the mouse, the FPS, and many more. Just check the UserDefaults.plist file located in the Resources folder in Smoke.framework.¹

Hacking the smoke framework

To get even more out of the smoke framework, you can edit various files within the framework itself. Most of the files are in the “Resources” folder. One of the most useful ones to edit is called boundary.cikernal. In the first two lines you can specify the height and width of the OpenGL view that the smoke appears in.

Enjoy the smoke!

Sample project

Developments

Austin has also graciously agreed to let me develop Fumo, the smoking Quicksilver interface.

Although there is still some talk about the HIG, usability, eye candy and so on, the controversy phase is mostly over. Speaking of which, you can call me what you like, but I think the HIG is definitely not dead. Outdated perhaps, but there needs to be a standard. There are many aspects to the existing HIG that developers need to follow in order to make the Mac experience enjoyable. I’ll talk about this in detail later. My rant about the HIG.

MagicHat is a programmer’s research and reference tool. With MagicHat, you navigate through Cocoa’s application programming interface (API); review the declarations of language elements such as methods, functions, and constants; and retrieve relevant passages from the Cocoa developer documentation. MagicHat helps you unravel unfamiliar code, whether building blocks from the Cocoa software kits, programming examples, or programs written by your own development team.

MagicHat lets you look at the declarations of public, private and local (installed) frameworks. This is a good graphical way to look at the structure of a framework, but is limited to Objective-C; which shouldn’t matter much for general use.

Above: MagicHat in action, displaying Disco.app’s Smoke.framework

Class-Dump

Class-Dump is one of the easiest to use command line utilities to look at the Objective-C portions of Mach-O files. The command is immediately available after moving the downloaded file to /usr/bin/ (you may need to use sudo mv). Executing it involves a running a simple “class-dump nameoffile” command in Terminal and the output is a nicely formatted Objective-C header. Objective-C output is the feature that makes this tool unique. It is especially useful if you need header files for frameworks which don’t include them, but it also gives you an idea as to the classes and methods present in the framework.

otool

otool provides one of the most comprehensive feature-sets - its primary role being to display parts of object files or libraries. You’ll generally find that using otool gives you access to frameworks such as CoreGraphics, which don’t contain Objective-C classes. The -v command will give you verbose output; -o displays the Objective-C and -t the text sections.

Take ‘em apart

Using these tools, you are now equipped to examine in detail most frameworks and libraries. Be aware that searching though and discovering new functions takes a lot of experimentation and trial and error - which the primary reason I leave it to people like Wade Tregaskis (who, like me, lives in Melbourne. Never met him, though).

Obligatory disclaimer: The private frameworks are probably private for a reason. Meddle with them at your own risk.

(For those adventurous souls, the Core Graphics framework is located at /System/Library/Frameworks/ApplicationServices.framework/Versions/A/Frameworks/CoreGraphics.framework but there are plenty of other private frameworks besides this one; Core Graphics just happens to have the window transition effects.

Ok, did this help, and what did I miss?

The function CGSSetWindowWarp is part of the private portion of Core Graphics. Although its just as obscure and undocumented as the rest of the private parts of the framework, there has been some discovery and progress into its usage. Erling Ellingsen has written (a while ago) about CGSSetWindowWarp on his blog, and he also shows some very interesting screenshots of what’s possible.

So, how do you use this incredible function in your Cocoa (or Carbon) application?

CGSSetWindowWarp Usage

Including the header

Whenever you use private Core Graphics functions, you generally need to #import either one of CoreGraphicsServices.h or CGSPrivate.h (available for download with my Core Graphics ebook). However, if you’re not interested in using the rest of the Core Graphics API, you can get away with simply adding the following to your main class’ header file:

typedef struct CGPointWarp {
        CGPoint local;
        CGPoint global;
}CGPointWarp;

typedef int CGSConnectionID;
typedef int CGSWindowID;

extern CGSConnectionID _CGSDefaultConnection();

extern CGError CGSSetWindowWarp(CGSConnectionID, CGSWindowID, int w, int h, CGPointWarp mesh[w][h]);
extern OSStatus CGSGetScreenRectForWindow(CGSConnectionID cid, CGSWindowID wid, CGRect *outRect);
extern OSStatus CGSGetWindowBounds(CGSConnectionID cid, CGSWindowID wid, CGRect *bounds);

As you’ve probably guessed, the function that actually applies the mesh transform is CGSSetWindowWarp. You can create a mesh in two different ways.

Creating the mesh

To create a mesh, we need to specify how many points we’re going to take for our grid length-wise and width-wise. Something like this:

#define H 64
#define W 5

We’ll also need to refer to the position and size of the frame so the following code in the method you’re writing this will give us access to the frame of the NSWindow:

CGRect frame;
CGSGetWindowBounds(cid, [window windowNumber], &frame);

The use of CGSGetWindowBounds ensures we get the apparent frame rather than just the frame computed by our code as we’ll be applying various transformations.

The first way to create a mesh requires more labor (yes, its tiring to code) but gives you greater control over the mesh and the transformations applied to the NSWindow.

Manual mesh

CGPointWarp meshes[H][W] =
{
{ {{0, 0},{10, 10}}, {{200,0},{180,12}} },
{ {{0, 50},{0,50}}, {{200,50},{200,50}} },
{ {{0,100},{0,100}}, {{200,100},{200,100}} },
{ {{0,150},{0,150}}, {{200,150},{200,150}} },
{ {{0,200},{0,200}}, {{200,200},{200,200}} },
};

Here, you specify firstly the coordinates of the point which you’re taking, and where you want to move that point. The first line in the above code takes (0,0) and moves it to (10,10) and moves (200,0) to (180,12). However, the first set of coordinates are local coordinates, and the second set are global. (ie., the first set are on the plane of the window, while the second set use the screen as the plane. This is to allow the window to be stretched out beyond the scope of the current frame.) We could solve this issue by using:

int x = frame.origin.x;
int y = frame.origin.y;
CGPointWarp meshes2[H][W] =
{
{ {{0, 0},{x, y}}, {{200,0},{x+200,y}} },
{ {{0, 50},{x,y+50}}, {{200,50},{x+200,y+50}} },
{ {{0,100},{x,y+100}}, {{200,100},{x+200,y+100}} },
{ {{0,150},{x,y+150}}, {{200,150},{x+200,y+150}} },
{ {{0,200},{x,y+200}}, {{200,200},{x+200,y+200}} },
};

The preceding code just warps the window of size 200×200 to its current position so no change is observable. If we wanted to stretch out the middle of the window horizontally, we could use a mesh in the form:

int x = frame.origin.x;
int y = frame.origin.y;
CGPointWarp stretchThroughMiddleMesh[H][W] =
{
{ {{0, 0},{x, y}}, {{200,0},{x+200,y}} },
{ {{0, 50},{x-10,y+50}}, {{200,50},{x+200+10,y+50}} },
{ {{0,100},{x-20,y+100}}, {{200,100},{x+200+20,y+100}} },
{ {{0,150},{x-10,y+150}}, {{200,150},{x+200+10,y+150}} },
{ {{0,200},{x,y+200}}, {{200,200},{x+200+10,y+200}} },
};

We’ve taken the side where x=0 and moved x further back along the middle, and done the opposite on the opposite side (where x=200). This results in the NSWindow being warped to have a bulge in the middle.

Again, this would only look like the screenshot on a window with a height and width of 200. For a window that’s a different size, you’ll need to change the values to match the height and width of the window. For the y-values in the mesh (x, x+50, x+100, etc. in the different rows), the numbers are determined by how many points you’ve taken (your value for H) and the width of the window. The general formula you would use would be x + ( frame.size.height / (W-1) ). You’ll see this more clearly in the second method.

Mesh through iterative formulae

The second method to create a mesh is to run a loop to configure your individual points. Here’s a basic example that creates a mesh that would be identical to the current state of the window:

int h;
int w;
CGPointWarp meshes[H][W];
for (h = 0; h < H; h++) {
    for (w = 0; w < W; w++) {
        CGPointWarp point;
        point.local.x = w * (frame.size.width / (W - 1));
        point.local.y = h * (frame.size.height / (H - 1));
        point.global.x = point.local.x + frame.origin.x;
        point.global.y = point.local.y + frame.origin.y;

        meshes[h][w] = point;
    }
}

Obviously we want to transform the window somehow. We need to apply some sort of mathematical function to the points to make them deviate from their original positions or coordinates. (This is the part where you start to wish you’d paid more attention in math class).

Lets say we want to skew the window using the x-axis. Each successive x-value needs to be greater than the previous one. Since we’re looping through each point, at any time in the inner for loop, the values of the current point are (w,h). (In Cartesian coordinates the x value is first, followed by the y value) In order to increase each successive value for x, we need to add something. But, we need to add more than what we did the previous time. The easiest way to do this without adding any new variables is to use the value that we’re incrementing each time - the x value itself. So, for a skewed window, we have the following mesh:

int h;
int w;
CGPointWarp meshes[H][W];
for (h = 0; h < H; h++) {
    for (w = 0; w < W; w++) {
        CGPointWarp point;
        point.local.x = w * (frame.size.width / (W - 1));
        point.local.y = h * (frame.size.height / (H - 1));
        point.global.x = point.local.x + frame.origin.x + 15*h;
        point.global.y = point.local.y + frame.origin.y;

        meshes[h][w] = point;
    }
}

The skewed window would like this when the mesh was applied:

Applying the mesh

The transform mesh was really the hard part. Applying the transformation mesh (or grid) to a window is as easy as:

CGSSetWindowWarp(_CGSDefaultConnection(), [window windowNumber], W, H, meshes);

The possibilities of this are really amazing. I’ve always wanted to write an NSWindow subclass that bent and reduced in opacity as it was dragged, imitating XGL. With CGSSetWindowWarp and Core Graphics, I’m sure it’ll be a breeze. Or what about an virtual universe-style Finder cross Desktop, sort of like 3DOSX? You could even imitate other effects with this, such as the cube, but still get live updating in your windows - a limitation present in the Core Graphics transition effects.

For a source code, and a further explanation, see Kevin Ballard’s post on the subject of CGSSetWindowWarp.

Did you find this useful? Or do you have any other method that you use for eye candy?

Heads-up-display with a window, subclassed with the framework.

With everyone trying to keep up with Apple’s interface additions, this isn’t a bad way to go about it. The framework includes a lot of subclasses and some of them needed to be added to Interface Builder in order for the hierarchy to show, so I’ve uploaded a simple project to show what this framework can do. It’s not completely bug-free; in fact, there are quite a number of creepy-crawlies, but the idea is there, and this looks to be the beginning of quite a handsome project.

Download sample project

Download just the framework source

And while you’re at it, don’t forget to thank Sean

If you’re like me, one of the first things you do when you see a cool app is dig straight into the resources folder. Well, right-clicking on Disco.app and hitting “Show package contents” is pretty revealing. Charge straight into the Contents folder, and you’ll see a nice little folder bearing the name “Frameworks”. Need I say any more? Just like all you need for Core Graphics is contained within my Core Graphics Framework, so the smoking windows code is contained in this little folder. It’s a simple matter of doing a class-dump to build some headers (or if you got in early, the headers are already there), and you have access to all the smoke you need. So, are you interested? Download the Disco beta and drag it to your applications folder. Then, you may proceed to grab a copy of my (modified) version of the smoking windows project and play around with it at your leisure! I quote from Toxic Software:

If your hardware is capable enough you should be able to see the smoke effect rising from the top of the window. (It might take 10 to 20 seconds for the smoke to appear). You can change the smoke parameters by using the smoke settings window (dialog? pane? view?) within Disco. Then just copy Disco’s prefs (com.discoapp.Disco.plist) to SecondHandSmoke’s prefs (com.example.SecondHandSmoke.plist).

Obviously, this way of setting preferences isn’t very flash, so you can just set the specific preference keys from within your code, and it’ll still run fine. Don’t expect that done from me, though, I’ve got a lot of work to catch up on. Then again, if someone wants to make their window smoke and can’t get their head around the preferences, I can always take a little break and help you out.

Second Hand Smoke

Have fun, and try not to get addicted to smoking.

Update: This smoke no longer works with the version 1.0 release of Disco. Updated smoking instructions here.

All the PPC / Intel specific bugs have been found, caught, and eradicated. The framework should now be ready for developer consumption for use in commercial apps, or for experimentation and utter bewilderment. Be amazed. Be very amazed, and download the framework straight from here or read and download it from the original post.

Now works on all architectures, and without hiccups!

Can’t get enough of window transitions? Love a little eye candy? Well, you’re in luck. The Core Graphics Framework and Xcode Project Template make adding the fantastic Core Graphics function to your app a breeze. In fact, it’s even more complete than the tutorial, and already has more features in it before you write a single line of code! It doesn’t stop there, however. This framework powerful enough to use the genie effect. That’s right. That awesome Mac OS X transform you can get when you minimize an application. Core Graphics contains a wealth of resources. You really have to check it out.

Point. Click. Zoom!

The CGS Framework is a an implementation of transitions, transforms and everything Core Graphics. It includes the definitions and implementations for the methods, so that using a transition or transform is as simple as calling a single method! For example, scaling a window is as simple as a “- scale: about:” call on the window, and rotating it just requires a single “- rotate: about:”. In the same way, Core Graphics is laid bare with this framework, for you to utilize at your pleasure!

Don't lift a finger

The framework does all the work for you, but even then, it gets simpler. Source for a sample app is included which means that you can create Core Graphics projects straight away by building on top of it. This saves you, the developer time in adding and linking the Framework, and reading and implementing the Core Graphics class in Interface Builder, as well as adding the framework to your project. A single double-click on the sample project and it’s all done for you. What more could you ask? Download a copy and check it out today. You’ll be surprised how powerful it is.

Gimme already!

Now a universal binary for your developing pleasure!

CGS Framework + Sample App

Once downloaded, open CoreGFX.app to view some of the possible effects. You can copy the source folder to hard drive if you need to build a Core Graphics enabled app. Enjoy the wonderfulness, and I hope you have fun!

Any queries, fire away.

Make sure you understand that some of the functions of Core Graphics used in this framework are undocumented, internal APIs that Apple haven’t released. (Calm down. It’s not illegal). Having said that, apps like Quicksilver would be quite bland without the use of the undocumented Core Graphics functions, so exercise your discretion.

This project relies heavily on work by Wade Tregaskis and his Rotating Windows.

© 2006 Ankur Kothari.