| 1 |
import * as utils from './utils'; |
| 2 |
import * as Backbone from 'backbone'; |
| 3 |
import { NativeView } from './nativeview'; |
| 4 |
import { JSONObject, JSONValue } from '@lumino/coreutils'; |
| 5 |
import { Message } from '@lumino/messaging'; |
| 6 |
import { Widget, Panel } from '@lumino/widgets'; |
| 7 |
import { LayoutModel } from './widget_layout'; |
| 8 |
import { StyleModel } from './widget_style'; |
| 9 |
import { IWidgetManager } from './manager'; |
| 10 |
import { IClassicComm, ICallbacks } from './services-shim'; |
| 11 |
import { BufferJSON, Dict } from './utils'; |
| 12 |
import { KernelMessage } from '@jupyterlab/services'; |
| 13 |
/** |
| 14 |
* Replace model ids with models recursively. |
| 15 |
*/ |
| 16 |
export declare function unpack_models(value: any | Dict<unknown> | string | (Dict<unknown> | string)[], manager?: IWidgetManager): Promise<WidgetModel | Dict<WidgetModel> | WidgetModel[] | any>; |
| 17 |
/** Replace models with ids recursively. |
| 18 |
* |
| 19 |
* If the commonly-used `unpack_models` is given as the `deseralize` method, |
| 20 |
* pack_models would be the appropriate `serialize`. |
| 21 |
* However, the default serialize method will have the same effect, when |
| 22 |
* `unpack_models` is used as the deserialize method. |
| 23 |
* This is to ensure backwards compatibility, see: |
| 24 |
* https://github.com/jupyter-widgets/ipywidgets/pull/3738/commits/f9e27328bb631eb5247a7a6563595d3e655492c7#diff-efb19099381ae8911dd7f69b015a0138d08da7164512c1ee112aa75100bc9be2 |
| 25 |
*/ |
| 26 |
export declare function pack_models(value: WidgetModel | Dict<WidgetModel> | WidgetModel[] | any, widget?: WidgetModel): any | Dict<unknown> | string | (Dict<unknown> | string)[]; |
| 27 |
/** |
| 28 |
* Type declaration for general widget serializers. |
| 29 |
*/ |
| 30 |
export interface ISerializers { |
| 31 |
[key: string]: { |
| 32 |
deserialize?: (value?: any, manager?: IWidgetManager) => any; |
| 33 |
serialize?: (value?: any, widget?: WidgetModel) => any; |
| 34 |
}; |
| 35 |
} |
| 36 |
export interface IBackboneModelOptions extends Backbone.ModelSetOptions { |
| 37 |
model_id: string; |
| 38 |
comm?: any; |
| 39 |
widget_manager: any; |
| 40 |
} |
| 41 |
export declare class WidgetModel extends Backbone.Model { |
| 42 |
/** |
| 43 |
* The default attributes. |
| 44 |
*/ |
| 45 |
defaults(): Backbone.ObjectHash; |
| 46 |
/** |
| 47 |
* Test to see if the model has been synced with the server. |
| 48 |
* |
| 49 |
* #### Notes |
| 50 |
* As of backbone 1.1, backbone ignores `patch` if it thinks the |
| 51 |
* model has never been pushed. |
| 52 |
*/ |
| 53 |
isNew(): boolean; |
| 54 |
/** |
| 55 |
* Constructor |
| 56 |
* |
| 57 |
* Initializes a WidgetModel instance. Called by the Backbone constructor. |
| 58 |
* |
| 59 |
* Parameters |
| 60 |
* ---------- |
| 61 |
* widget_manager : WidgetManager instance |
| 62 |
* model_id : string |
| 63 |
* An ID unique to this model. |
| 64 |
* comm : Comm instance (optional) |
| 65 |
*/ |
| 66 |
initialize(attributes: Backbone.ObjectHash, options: IBackboneModelOptions): void; |
| 67 |
get comm_live(): boolean; |
| 68 |
set comm_live(x: boolean); |
| 69 |
/** |
| 70 |
* Send a custom msg over the comm. |
| 71 |
*/ |
| 72 |
send(content: JSONValue, callbacks?: ICallbacks, buffers?: ArrayBuffer[] | ArrayBufferView[]): void; |
| 73 |
/** |
| 74 |
* Close model |
| 75 |
* |
| 76 |
* @param comm_closed - true if the comm is already being closed. If false, the comm will be closed. |
| 77 |
* |
| 78 |
* @returns - a promise that is fulfilled when all the associated views have been removed. |
| 79 |
*/ |
| 80 |
close(comm_closed?: boolean): Promise<void>; |
| 81 |
/** |
| 82 |
* Handle when a widget comm is closed. |
| 83 |
*/ |
| 84 |
_handle_comm_closed(msg: KernelMessage.ICommCloseMsg): void; |
| 85 |
/** |
| 86 |
* Handle incoming comm msg. |
| 87 |
*/ |
| 88 |
_handle_comm_msg(msg: KernelMessage.ICommMsgMsg): Promise<void>; |
| 89 |
/** |
| 90 |
* Handle when a widget is updated from the backend. |
| 91 |
* |
| 92 |
* This function is meant for internal use only. Values set here will not be propagated on a sync. |
| 93 |
*/ |
| 94 |
set_state(state: Dict<unknown>): void; |
| 95 |
/** |
| 96 |
* Get the serializable state of the model. |
| 97 |
* |
| 98 |
* If drop_default is truthy, attributes that are equal to their default |
| 99 |
* values are dropped. |
| 100 |
*/ |
| 101 |
get_state(drop_defaults?: boolean): JSONObject; |
| 102 |
/** |
| 103 |
* Handle status msgs. |
| 104 |
* |
| 105 |
* execution_state : ('busy', 'idle', 'starting') |
| 106 |
*/ |
| 107 |
_handle_status(msg: KernelMessage.IStatusMsg): void; |
| 108 |
/** |
| 109 |
* Create msg callbacks for a comm msg. |
| 110 |
*/ |
| 111 |
callbacks(view?: WidgetView): ICallbacks; |
| 112 |
/** |
| 113 |
* Set one or more values. |
| 114 |
* |
| 115 |
* We just call the super method, in which val and options are optional. |
| 116 |
* Handles both "key", value and {key: value} -style arguments. |
| 117 |
*/ |
| 118 |
set(key: any, val?: any, options?: any): any; |
| 119 |
/** |
| 120 |
* Handle sync to the back-end. Called when a model.save() is called. |
| 121 |
* |
| 122 |
* Make sure a comm exists. |
| 123 |
* |
| 124 |
* Parameters |
| 125 |
* ---------- |
| 126 |
* method : create, update, patch, delete, read |
| 127 |
* create/update always send the full attribute set |
| 128 |
* patch - only send attributes listed in options.attrs, and if we |
| 129 |
* are queuing up messages, combine with previous messages that have |
| 130 |
* not been sent yet |
| 131 |
* model : the model we are syncing |
| 132 |
* will normally be the same as `this` |
| 133 |
* options : dict |
| 134 |
* the `attrs` key, if it exists, gives an {attr: value} dict that |
| 135 |
* should be synced, otherwise, sync all attributes. |
| 136 |
* |
| 137 |
*/ |
| 138 |
sync(method: string, model: WidgetModel, options?: any): any; |
| 139 |
rememberLastUpdateFor(msgId: string): void; |
| 140 |
/** |
| 141 |
* Serialize widget state. |
| 142 |
* |
| 143 |
* A serializer is a function which takes in a state attribute and a widget, |
| 144 |
* and synchronously returns a JSONable object. The returned object will |
| 145 |
* have toJSON called if possible, and the final result should be a |
| 146 |
* primitive object that is a snapshot of the widget state that may have |
| 147 |
* binary array buffers. |
| 148 |
*/ |
| 149 |
serialize(state: Dict<any>): JSONObject; |
| 150 |
/** |
| 151 |
* Send a sync message to the kernel. |
| 152 |
* |
| 153 |
* If a message is sent successfully, this returns the message ID of that |
| 154 |
* message. Otherwise it returns an empty string |
| 155 |
*/ |
| 156 |
send_sync_message(state: JSONObject, callbacks?: any): string; |
| 157 |
/** |
| 158 |
* Push this model's state to the back-end |
| 159 |
* |
| 160 |
* This invokes a Backbone.Sync. |
| 161 |
*/ |
| 162 |
save_changes(callbacks?: {}): void; |
| 163 |
/** |
| 164 |
* on_some_change(['key1', 'key2'], foo, context) differs from |
| 165 |
* on('change:key1 change:key2', foo, context). |
| 166 |
* If the widget attributes key1 and key2 are both modified, |
| 167 |
* the second form will result in foo being called twice |
| 168 |
* while the first will call foo only once. |
| 169 |
*/ |
| 170 |
on_some_change(keys: string[], callback: (...args: any[]) => void, context: any): void; |
| 171 |
/** |
| 172 |
* Serialize the model. See the deserialization function at the top of this file |
| 173 |
* and the kernel-side serializer/deserializer. |
| 174 |
*/ |
| 175 |
toJSON(options?: {}): string; |
| 176 |
/** |
| 177 |
* Returns a promise for the deserialized state. The second argument |
| 178 |
* is an instance of widget manager, which is required for the |
| 179 |
* deserialization of widget models. |
| 180 |
*/ |
| 181 |
static _deserialize_state(state: Dict<BufferJSON>, manager: IWidgetManager): Promise<utils.Dict<unknown>>; |
| 182 |
static serializers: ISerializers; |
| 183 |
widget_manager: IWidgetManager; |
| 184 |
model_id: string; |
| 185 |
views?: { |
| 186 |
[key: string]: Promise<WidgetView>; |
| 187 |
}; |
| 188 |
state_change: Promise<any>; |
| 189 |
comm?: IClassicComm; |
| 190 |
name: string; |
| 191 |
module: string; |
| 192 |
private _comm_live; |
| 193 |
private _closed; |
| 194 |
private _state_lock; |
| 195 |
private _buffered_state_diff; |
| 196 |
private _buffered_state_diff_synced; |
| 197 |
private _msg_buffer; |
| 198 |
private _msg_buffer_callbacks; |
| 199 |
private _pending_msgs; |
| 200 |
private _expectedEchoMsgIds; |
| 201 |
private _attrsToUpdate; |
| 202 |
} |
| 203 |
export declare class DOMWidgetModel extends WidgetModel { |
| 204 |
static serializers: ISerializers; |
| 205 |
defaults(): Backbone.ObjectHash; |
| 206 |
} |
| 207 |
export declare class WidgetView extends NativeView<WidgetModel> { |
| 208 |
/** |
| 209 |
* Public constructor. |
| 210 |
*/ |
| 211 |
constructor(options?: Backbone.ViewOptions<WidgetModel> & { |
| 212 |
options?: any; |
| 213 |
}); |
| 214 |
/** |
| 215 |
* Initializer, called at the end of the constructor. |
| 216 |
*/ |
| 217 |
initialize(parameters: WidgetView.IInitializeParameters): void; |
| 218 |
/** |
| 219 |
* Handle message sent to the front end. |
| 220 |
* |
| 221 |
* Used to focus or blur the widget. |
| 222 |
*/ |
| 223 |
handle_message(content: any): void; |
| 224 |
/** |
| 225 |
* Triggered on model change. |
| 226 |
* |
| 227 |
* Update view to be consistent with this.model |
| 228 |
*/ |
| 229 |
update(options?: any): void; |
| 230 |
/** |
| 231 |
* Render a view |
| 232 |
* |
| 233 |
* @returns the view or a promise to the view. |
| 234 |
*/ |
| 235 |
render(): any; |
| 236 |
/** |
| 237 |
* Create and promise that resolves to a child view of a given model |
| 238 |
*/ |
| 239 |
create_child_view<VT extends DOMWidgetView = DOMWidgetView>(child_model: DOMWidgetModel, options?: any): Promise<VT>; |
| 240 |
create_child_view<VT extends WidgetView = WidgetView>(child_model: WidgetModel, options?: any): Promise<VT>; |
| 241 |
/** |
| 242 |
* Create msg callbacks for a comm msg. |
| 243 |
*/ |
| 244 |
callbacks(): ICallbacks; |
| 245 |
/** |
| 246 |
* Send a custom msg associated with this view. |
| 247 |
*/ |
| 248 |
send(content: {}, buffers?: ArrayBuffer[] | ArrayBufferView[]): void; |
| 249 |
touch(): void; |
| 250 |
remove(): any; |
| 251 |
options: any; |
| 252 |
/** |
| 253 |
* A promise that resolves to the parent view when a child view is displayed. |
| 254 |
*/ |
| 255 |
displayed: Promise<WidgetView>; |
| 256 |
} |
| 257 |
export declare namespace WidgetView { |
| 258 |
interface IInitializeParameters<T extends WidgetModel = WidgetModel> extends Backbone.ViewOptions<T> { |
| 259 |
options: any; |
| 260 |
} |
| 261 |
} |
| 262 |
export declare namespace JupyterLuminoWidget { |
| 263 |
interface IOptions { |
| 264 |
view: DOMWidgetView; |
| 265 |
} |
| 266 |
} |
| 267 |
export declare class JupyterLuminoWidget extends Widget { |
| 268 |
constructor(options: Widget.IOptions & JupyterLuminoWidget.IOptions); |
| 269 |
/** |
| 270 |
* Dispose the widget. |
| 271 |
* |
| 272 |
* This causes the view to be destroyed as well with 'remove' |
| 273 |
*/ |
| 274 |
dispose(): void; |
| 275 |
/** |
| 276 |
* Process the Lumino message. |
| 277 |
* |
| 278 |
* Any custom Lumino widget used inside a Jupyter widget should override |
| 279 |
* the processMessage function like this. |
| 280 |
*/ |
| 281 |
processMessage(msg: Message): void; |
| 282 |
private _view; |
| 283 |
} |
| 284 |
/** |
| 285 |
* @deprecated Use {@link JupyterLuminoWidget} instead (Since 8.0). |
| 286 |
*/ |
| 287 |
export declare const JupyterPhosphorWidget: typeof JupyterLuminoWidget; |
| 288 |
export declare class JupyterLuminoPanelWidget extends Panel { |
| 289 |
constructor(options: JupyterLuminoWidget.IOptions & Panel.IOptions); |
| 290 |
/** |
| 291 |
* Process the Lumino message. |
| 292 |
* |
| 293 |
* Any custom Lumino widget used inside a Jupyter widget should override |
| 294 |
* the processMessage function like this. |
| 295 |
*/ |
| 296 |
processMessage(msg: Message): void; |
| 297 |
/** |
| 298 |
* Dispose the widget. |
| 299 |
* |
| 300 |
* This causes the view to be destroyed as well with 'remove' |
| 301 |
*/ |
| 302 |
dispose(): void; |
| 303 |
private _view; |
| 304 |
} |
| 305 |
/** |
| 306 |
* @deprecated Use {@link JupyterLuminoPanelWidget} instead (Since 8.0). |
| 307 |
*/ |
| 308 |
export declare const JupyterPhosphorPanelWidget: typeof JupyterLuminoPanelWidget; |
| 309 |
export declare class DOMWidgetView extends WidgetView { |
| 310 |
/** |
| 311 |
* Public constructor |
| 312 |
*/ |
| 313 |
initialize(parameters: WidgetView.IInitializeParameters): void; |
| 314 |
setLayout(layout: LayoutModel, oldLayout?: LayoutModel): void; |
| 315 |
setStyle(style: StyleModel, oldStyle?: StyleModel): void; |
| 316 |
updateTooltip(): void; |
| 317 |
/** |
| 318 |
* Update the DOM classes applied to an element, default to this.el. |
| 319 |
*/ |
| 320 |
update_classes(old_classes: string[], new_classes: string[], el?: HTMLElement): void; |
| 321 |
/** |
| 322 |
* Update the DOM classes applied to the widget based on a single |
| 323 |
* trait's value. |
| 324 |
* |
| 325 |
* Given a trait value classes map, this function automatically |
| 326 |
* handles applying the appropriate classes to the widget element |
| 327 |
* and removing classes that are no longer valid. |
| 328 |
* |
| 329 |
* Parameters |
| 330 |
* ---------- |
| 331 |
* class_map: dictionary |
| 332 |
* Dictionary of trait values to class lists. |
| 333 |
* Example: |
| 334 |
* { |
| 335 |
* success: ['alert', 'alert-success'], |
| 336 |
* info: ['alert', 'alert-info'], |
| 337 |
* warning: ['alert', 'alert-warning'], |
| 338 |
* danger: ['alert', 'alert-danger'] |
| 339 |
* }; |
| 340 |
* trait_name: string |
| 341 |
* Name of the trait to check the value of. |
| 342 |
* el: optional DOM element handle, defaults to this.el |
| 343 |
* Element that the classes are applied to. |
| 344 |
*/ |
| 345 |
update_mapped_classes(class_map: Dict<string[]>, trait_name: string, el?: HTMLElement): void; |
| 346 |
set_mapped_classes(class_map: Dict<string[]>, trait_name: string, el?: HTMLElement): void; |
| 347 |
_setElement(el: HTMLElement): void; |
| 348 |
remove(): any; |
| 349 |
processLuminoMessage(msg: Message): void; |
| 350 |
private _comm_live_update; |
| 351 |
updateTabindex(): void; |
| 352 |
/** |
| 353 |
* @deprecated Use {@link luminoWidget} instead (Since 8.0). |
| 354 |
*/ |
| 355 |
get pWidget(): Widget; |
| 356 |
/** |
| 357 |
* @deprecated Use {@link luminoWidget} instead (Since 8.0). |
| 358 |
*/ |
| 359 |
set pWidget(value: Widget); |
| 360 |
el: HTMLElement; |
| 361 |
'$el': any; |
| 362 |
luminoWidget: Widget; |
| 363 |
layoutPromise: Promise<any>; |
| 364 |
stylePromise: Promise<any>; |
| 365 |
} |
| 366 |
//# sourceMappingURL=widget.d.ts.map |