Tutorial

Vvidget Code > Programming > Plug-in > Tutorial

This tutorial shows how to use Vvidget Code without the appearance of a user interface. The particular usage is a QuickLook Plug-in, however the same methodology applies to any other similar need.

The basic steps for such a situation, which are elaborated on in later sections, are as follows:

Step	Description
Prerequisites	You will have to install the Apple Xcode developer tools and the appropriate Vvidget packages. Both can be downloaded online if you do not already have them.
New Project	Launch Xcode, located on your computer at /Developer/Applications/Xcode, and make a new Plug-in project.
Vvidget Capability	Xcode does not come with Vvidget capability so you will have to explicitly add it to your application. Adding the capability is a matter of properly referencing the Vvidget Frameworks (libraries).
Source Code	Add the source code as described below. The source code includes Vvidget API references, so you need to add the Vvidget capability first as was done in the previous step.
Build And Install	Installing is simply a matter of dragging the build result to a particular destination.
Refining	Your plug-in is simply a handful of code. The code you write results in the functionality you desire.

The following describes the steps above in greater detail.

Prerequisites

Download and install Xcode. If you have not done this before then click: http://developer.apple.com/devcenter/mac to get started or insert the Mac OS X install disk into your computer, locate the Xcode package and install. If you are updating Xcode then I suggest that you uninstall it first (see its notes), reboot, install the new version and then reboot.

If you have not already done so, go to http://www.vvidget.org/download and download and install the Vvidget Code package. For completeness sake, you should logout and then login to your home account. That is because there are some Vvidget components used in development that are based on services, whereas an end user application such as Vvidget Builder or an application you write does not have that issue. In any event a logout and in or a reboot is a nicety of the development environment and may not be needed.

Make A New Project

Launch Xcode, located on your computer at /Developer/Applications/Xcode, and in its main menu click File > New Project .... and then from the New Project panel select the System Plug-in > Quick Look Plug-In template.

Add Vvidget Capability

Xcode does not come with Vvidget capability so you will have to explicitly add it to your application. Adding the capability is a matter of properly referencing the Vvidget Frameworks (libraries). In your project, click the "External Frameworks and Libraries" Group and then click the menu item Project > Add to Project ... From there, navigate to the /Library/Frameworks directory click on the VvidgetCode.framework and then click the Add button. In the resulting panel note that the target for your project is checked and then click the Add button. Your project now has Vvidget Capability. This step contrasts sharply with that in the Cocoa Programming Tutorial where the Vvidget Embedded Frameworks are used. Because the non-embedded framework form is being used in this tutorial, you need to make sure that Vvidget User is installed on your computer as well as other computers that you intend to run your plug-in on. Note that you can also write a Cocoa Application with the non-embedded frameworks as well and that is certainly a legitimate use.

Source Code

In this step you will add Vvidget processing. Click on the GeneratePreviewForURL.m file and add the following to include Vvidget Code definitions:


#include <VvidgetCode/VvidgetCode.h>

then paste the following code into its GeneratePreviewForURL() function.


OSStatus GeneratePreviewForURL(void *thisInterface, QLPreviewRequestRef preview, CFURLRef url, CFStringRef contentTypeUTI, CFDictionaryRef options)

{



UInt8 filePath[1024];

NSAutoreleasePool *pool;



pool = [[NSAutoreleasePool alloc] init];



CFURLGetFileSystemRepresentation(url, TRUE, filePath, 1024);



VC_Client_State *client_state;

VC_Input_String_Constructor *input_string_constructor;

NSData *image_data;

unsigned width, height;

unsigned image_output_type;



image_output_type = 1U;

width = 800U;

height = 600U;



client_state = [[VC_Client_State alloc] init];

constructor = [client_state get_VC_input_string_constructor]; // by reference only



[constructor VC_reset];



[constructor VC_append_key:"pvs_version" unsigned_value:1U];



[constructor VC_append_key:"vvidgetcode_deployment_license" string_value:@"embedded 1d65ch78f09aadR06464fY6"];



[constructor VC_append_key:"image_maker" string_value:@"chart"];

[constructor VC_append_key:"chart_type" string_value:@"line"];

[constructor VC_append_key:"chart_subtype" string_value:@"linear"];

[constructor VC_append_key:"chart_format_type" string_value:@"default"];



[constructor VC_append_key:"title" string_value:@"Line Graph Quick Look"];

[constructor VC_append_key:"x_title" string_value:@"X"];

[constructor VC_append_key:"y_title" string_value:@"Y"];



[constructor VC_append_key:"data_format_type" unsigned_value:0U];

[constructor VC_append_key:"data_reference_type" unsigned_value:1U];

[constructor VC_append_key:"data_values" string_value:[NSString stringWithUTF8String:filePath]];



[constructor VC_append_key:"image_width" unsigned_value:width];

[constructor VC_append_key:"image_height" unsigned_value:height];

[constructor VC_append_key:"image_output_type" unsigned_value:image_output_type];



[client_state VC_update_using_host_string:@"localhost"];

[client_state set_VC_image_output_type:image_output_type];

[client_state set_VC_image_width:width];

[client_state set_VC_image_height:height];



[client_state VC_update_using_input_string_constructor];



[client_state VC_form_query_data];



image_data = [client_state VC_output_data_from_query_data:[client_state get_VC_query_data]];



[client_state VC_invalidate_connection];



if(image_data != nil)

{

QLPreviewRequestSetDataRepresentation(preview, (CFDataRef)image_data, kUTTypeImage, NULL);



[image_data release];

}



[client_state release];

[pool release];



return noErr;

}

Do a similar thing to add other needed functionality, for example to add Thumbnail processing.

There are a few interesting things to note in the code:

The code uses a Client State instance instead of a VvidgetCodeClientView instance. That means that the processing simply uses an object that maintains state information required for a result and does not use any of the heavy machinery of the Cocoa View mechanisms.
The code redirects processing via the call: [client_state VC_update_using_host_string:@"localhost"] to the Vvidget Server running on the computer. That server was installed when you installed the VvidgetUser package. If you don't like that dependency then you can eliminate that as described in the Refine section below.
The code is pretty much self explanatory and cookie-cutter use of the Dictionary keys and values. Most of the work involved in this tutorial is knowing which dictionary entries to add.

Build And Install

Next click the Build button and then drag the resulting plug-in to the /Library/QuickLook directory. There is a slight problem with Xcode version 3.2.1 (the one used for this tutorial): The "Build and Run" button is disabled so it appears that you can not build the plug-in. To remedy this, click the menu item Build > Build, or enter the Build icon into the toolbar of Xcode and click that. Xcode is smart enough to know it can not run the plug-in, but not so smart that it changes the "Build and Run" button to a simple "Build" button; a minor detail.

Refining

The plug-in is straight forward and there is not much refining to do but perhaps these are some suggestions:

• Unlike the Cocoa Programming Tutorial, this tutorial uses the Vvidget Server, a separate process, to handle the graphics processing. This allows for some nice features: The plug-in is small, it does not require graphics processing and it minimizes the amount of symbols imported into the process the plug-in is loaded into. This is not a requirement however and the plug-in can be made to process within its own process space by following the Add Vvidget Capability section in the Cocoa Programming Tutorial. Conversely, a Cocoa application can be made to operate like the plug-in of this tutorial by following the Add Vvidget Capability of this tutorial instead of what is presented in the Cocoa Tutorial.

• You can add a lot more functionality to the plug-in but that is beyond the scope of this tutorial. You can also add this same exact code to a simple unix command line tool to implement Vvidget processing without the embellishments of a user interface.

• You can download and read about the plug-in project described in this tutorial at the Line Graph QuickLook section.

Conclusion

By following the few steps above you can create a plug-in or any other program that retrieves a Vvidget Code result. Once you have the result, in the form of an image or other export type, then you can insert that into other processes or systems that take that type of result as input. The QuickLook plug-in is a natural for this type of use, however there are many other situations that are equally if not more applicable.

Please help improve this documentation. If a section is hard to understand, there is a typo, you would like a new section added, or you detect any other improvement that can be made then please email support@vvi.com with your information.

© Copyright 1993-2011 by VVimaging, Inc. (VVI); All Rights Reserved. Please email support@vvi.com with any comments you have concerning this documentation. See Legal for trademark and legal information.

•	Unlike the Cocoa Programming Tutorial, this tutorial uses the Vvidget Server, a separate process, to handle the graphics processing. This allows for some nice features: The plug-in is small, it does not require graphics processing and it minimizes the amount of symbols imported into the process the plug-in is loaded into. This is not a requirement however and the plug-in can be made to process within its own process space by following the Add Vvidget Capability section in the Cocoa Programming Tutorial. Conversely, a Cocoa application can be made to operate like the plug-in of this tutorial by following the Add Vvidget Capability of this tutorial instead of what is presented in the Cocoa Tutorial.
•	You can add a lot more functionality to the plug-in but that is beyond the scope of this tutorial. You can also add this same exact code to a simple unix command line tool to implement Vvidget processing without the embellishments of a user interface.
•	You can download and read about the plug-in project described in this tutorial at the Line Graph QuickLook section.