0
# Programmatic Control
1

2
Methods for controlling the VueCropper component programmatically, including crop operations, image transformations, and data extraction.
3

4
## Capabilities
5

6
### Crop Control Methods
7

8
Methods for managing the cropping interface and crop box state.
9

10
```javascript { .api }
11
/**
12
 * Begin cropping mode and show crop box
13
 */
14
startCrop(): void;
15

16
/**
17
 * Exit cropping mode and hide crop box
18
 */
19
stopCrop(): void;
20

21
/**
22
 * Remove crop box and clear cropping area
23
 */
24
clearCrop(): void;
25

26
/**
27
 * Generate automatic crop box based on current settings
28
 * @param w - Optional crop box width
29
 * @param h - Optional crop box height
30
 */
31
goAutoCrop(w?: number, h?: number): void;
32
```
33

34
**Usage Examples:**
35

36
```vue
37
<template>
38
  <div class="cropper-container">
39
    <VueCropper ref="cropper" :img="imageUrl" />
40
    
41
    <div class="controls">
42
      <button @click="startCropping">Start Crop</button>
43
      <button @click="stopCropping">Stop Crop</button>
44
      <button @click="clearCropping">Clear Crop</button>
45
      <button @click="autoGenerate">Auto Generate</button>
46
    </div>
47
  </div>
48
</template>
49

50
<script>
51
export default {
52
  data() {
53
    return {
54
      imageUrl: '/path/to/image.jpg'
55
    };
56
  },
57
  methods: {
58
    startCropping() {
59
      this.$refs.cropper.startCrop();
60
      this.isCropping = true;
61
    },
62
    
63
    stopCropping() {
64
      this.$refs.cropper.stopCrop();
65
      this.isCropping = false;
66
    },
67
    
68
    clearCropping() {
69
      this.$refs.cropper.clearCrop();
70
      this.cropCleared = true;
71
    },
72
    
73
    autoGenerate() {
74
      // First ensure auto crop settings are configured
75
      this.$refs.cropper.goAutoCrop();
76
    }
77
  }
78
};
79
</script>
80
```
81

82
### Image Transformation Methods
83

84
Methods for manipulating the image display and orientation.
85

86
```javascript { .api }
87
/**
88
 * Scale/zoom the image
89
 * @param delta - Positive values zoom in, negative values zoom out
90
 */
91
changeScale(delta: number): void;
92

93
/**
94
 * Rotate image 90 degrees counter-clockwise
95
 */
96
rotateLeft(): void;
97

98
/**
99
 * Rotate image 90 degrees clockwise  
100
 */
101
rotateRight(): void;
102

103
/**
104
 * Reset component to initial state
105
 */
106
refresh(): void;
107

108
/**
109
 * Clear all rotation and reset to 0 degrees
110
 */
111
rotateClear(): void;
112

113
/**
114
 * Manually change crop box dimensions
115
 * @param w - New crop box width
116
 * @param h - New crop box height
117
 */
118
changeCrop(w: number, h: number): void;
119

120
/**
121
 * Position crop box programmatically
122
 * @param event - Optional event object
123
 * @param isMove - Optional move flag
124
 */
125
moveCrop(event?: Event, isMove?: boolean): void;
126
```
127

128
**Usage Examples:**
129

130
```vue
131
<template>
132
  <div class="image-editor">
133
    <VueCropper ref="cropper" :img="imageUrl" />
134
    
135
    <div class="transformation-controls">
136
      <div class="zoom-controls">
137
        <button @click="zoomIn">Zoom In</button>
138
        <button @click="zoomOut">Zoom Out</button>
139
        <button @click="resetZoom">Reset</button>
140
      </div>
141
      
142
      <div class="rotation-controls">
143
        <button @click="rotateCounterClockwise">↺ Rotate Left</button>
144
        <button @click="rotateClockwise">↻ Rotate Right</button>
145
      </div>
146
      
147
      <div class="general-controls">
148
        <button @click="resetAll">Reset All</button>
149
      </div>
150
    </div>
151
  </div>
152
</template>
153

154
<script>
155
export default {
156
  data() {
157
    return {
158
      imageUrl: '/path/to/image.jpg',
159
      currentZoom: 1
160
    };
161
  },
162
  methods: {
163
    zoomIn() {
164
      this.$refs.cropper.changeScale(0.1);
165
      this.currentZoom += 0.1;
166
    },
167
    
168
    zoomOut() {
169
      this.$refs.cropper.changeScale(-0.1);
170
      this.currentZoom = Math.max(0.1, this.currentZoom - 0.1);
171
    },
172
    
173
    resetZoom() {
174
      // Reset to original scale
175
      const resetAmount = 1 - this.currentZoom;
176
      this.$refs.cropper.changeScale(resetAmount);
177
      this.currentZoom = 1;
178
    },
179
    
180
    rotateCounterClockwise() {
181
      this.$refs.cropper.rotateLeft();
182
      this.rotationAngle = (this.rotationAngle - 90) % 360;
183
    },
184
    
185
    rotateClockwise() {
186
      this.$refs.cropper.rotateRight();  
187
      this.rotationAngle = (this.rotationAngle + 90) % 360;
188
    },
189
    
190
    resetAll() {
191
      this.$refs.cropper.refresh();
192
      this.currentZoom = 1;
193
      this.rotationAngle = 0;
194
    },
195
    
196
    resetRotation() {
197
      this.$refs.cropper.rotateClear();
198
      this.rotationAngle = 0;
199
    },
200
    
201
    setCropSize() {
202
      // Set crop box to specific dimensions
203
      this.$refs.cropper.changeCrop(300, 200);
204
    }
205
  }
206
};
207
</script>
208
```
209

210
### Data Extraction Methods
211

212
Methods for retrieving the cropped image data in different formats.
213

214
```javascript { .api }
215
/**
216
 * Get cropped image as base64 data URL
217
 * @param callback - Function called with base64 string result
218
 */
219
getCropData(callback: (base64: string) => void): void;
220

221
/**
222
 * Get cropped image as Blob object
223
 * @param callback - Function called with Blob result
224
 */
225
getCropBlob(callback: (blob: Blob) => void): void;
226
```
227

228
**Usage Examples:**
229

230
```vue
231
<template>
232
  <div class="export-interface">
233
    <VueCropper ref="cropper" :img="imageUrl" />
234
    
235
    <div class="export-controls">
236
      <button @click="downloadImage">Download Image</button>
237
      <button @click="uploadToServer">Upload to Server</button>
238
      <button @click="showPreview">Show Preview</button>
239
    </div>
240
    
241
    <div v-if="previewUrl" class="preview-result">
242
      <h3>Cropped Result:</h3>
243
      <img :src="previewUrl" alt="Cropped image" />
244
    </div>
245
  </div>
246
</template>
247

248
<script>
249
export default {
250
  data() {
251
    return {
252
      imageUrl: '/path/to/image.jpg',
253
      previewUrl: null
254
    };
255
  },
256
  methods: {
257
    downloadImage() {
258
      this.$refs.cropper.getCropData((data) => {
259
        // Create download link
260
        const link = document.createElement('a');
261
        link.href = data;
262
        link.download = 'cropped-image.jpg';
263
        document.body.appendChild(link);
264
        link.click();
265
        document.body.removeChild(link);
266
      });
267
    },
268
    
269
    async uploadToServer() {
270
      this.$refs.cropper.getCropBlob(async (blob) => {
271
        const formData = new FormData();
272
        formData.append('image', blob, 'cropped-image.jpg');
273
        
274
        try {
275
          const response = await fetch('/api/upload', {
276
            method: 'POST',
277
            body: formData
278
          });
279
          
280
          if (response.ok) {
281
            const result = await response.json();
282
            console.log('Upload successful:', result);
283
            this.$emit('upload-success', result);
284
          } else {
285
            throw new Error('Upload failed');
286
          }
287
        } catch (error) {
288
          console.error('Upload error:', error);
289
          this.$emit('upload-error', error);
290
        }
291
      });
292
    },
293
    
294
    showPreview() {
295
      this.$refs.cropper.getCropData((data) => {
296
        this.previewUrl = data;
297
      });
298
    }
299
  }
300
};
301
</script>
302
```
303

304
### Position and Dimension Methods
305

306
Methods for retrieving coordinate and dimension information.
307

308
```javascript { .api }
309
/**
310
 * Get image position relative to container
311
 * @param x - Optional x coordinate parameter
312
 * @param y - Optional y coordinate parameter  
313
 * @param scale - Optional scale parameter
314
 * @returns Axis coordinates of the image
315
 */
316
getImgAxis(x?: number, y?: number, scale?: number): AxisData;
317

318
/**
319
 * Get crop box position relative to container  
320
 * @returns Axis coordinates of the crop box
321
 */
322
getCropAxis(): AxisData;
323

324
interface AxisData {
325
  x1: number;  // top-left x coordinate
326
  x2: number;  // bottom-right x coordinate
327
  y1: number;  // top-left y coordinate  
328
  y2: number;  // bottom-right y coordinate
329
}
330
```
331

332
**Usage Examples:**
333

334
```vue
335
<template>
336
  <div class="coordinate-inspector">
337
    <VueCropper ref="cropper" :img="imageUrl" />
338
    
339
    <div class="info-panel">
340
      <button @click="updateCoordinates">Update Coordinates</button>
341
      
342
      <div class="coordinates-display">
343
        <h4>Image Coordinates:</h4>
344
        <p>Top-left: ({{ imageCoords.x1 }}, {{ imageCoords.y1 }})</p>
345
        <p>Bottom-right: ({{ imageCoords.x2 }}, {{ imageCoords.y2 }})</p>
346
        
347
        <h4>Crop Box Coordinates:</h4>
348
        <p>Top-left: ({{ cropCoords.x1 }}, {{ cropCoords.y1 }})</p>
349
        <p>Bottom-right: ({{ cropCoords.x2 }}, {{ cropCoords.y2 }})</p>
350
        
351
        <h4>Crop Dimensions:</h4>
352
        <p>Width: {{ cropCoords.x2 - cropCoords.x1 }}px</p>
353
        <p>Height: {{ cropCoords.y2 - cropCoords.y1 }}px</p>
354
      </div>
355
    </div>
356
  </div>
357
</template>
358

359
<script>
360
export default {
361
  data() {
362
    return {
363
      imageUrl: '/path/to/image.jpg',
364
      imageCoords: { x1: 0, y1: 0, x2: 0, y2: 0 },
365
      cropCoords: { x1: 0, y1: 0, x2: 0, y2: 0 }
366
    };
367
  },
368
  methods: {
369
    updateCoordinates() {
370
      this.imageCoords = this.$refs.cropper.getImgAxis();
371
      this.cropCoords = this.$refs.cropper.getCropAxis();
372
      
373
      // Calculate additional metrics
374
      const cropWidth = this.cropCoords.x2 - this.cropCoords.x1;
375
      const cropHeight = this.cropCoords.y2 - this.cropCoords.y1;
376
      const cropArea = cropWidth * cropHeight;
377
      
378
      console.log('Crop area:', cropArea, 'pixels');
379
      
380
      // Validate crop position
381
      this.validateCropPosition();
382
    },
383
    
384
    validateCropPosition() {
385
      const imgBounds = this.imageCoords;
386
      const cropBounds = this.cropCoords;
387
      
388
      const isWithinBounds = 
389
        cropBounds.x1 >= imgBounds.x1 &&
390
        cropBounds.y1 >= imgBounds.y1 &&
391
        cropBounds.x2 <= imgBounds.x2 &&
392
        cropBounds.y2 <= imgBounds.y2;
393
        
394
      if (!isWithinBounds) {
395
        console.warn('Crop box extends beyond image boundaries');
396
      }
397
    }
398
  }
399
};
400
</script>
401
```
402

403
### Component Properties
404

405
Read-only properties accessible via component reference.
406

407
```javascript { .api }
408
/**
409
 * Current crop box width in pixels
410
 */
411
readonly cropW: number;
412

413
/**
414
 * Current crop box height in pixels  
415
 */
416
readonly cropH: number;
417
```
418

419
**Usage Examples:**
420

421
```vue
422
<template>
423
  <div class="dimension-monitor">
424
    <VueCropper ref="cropper" :img="imageUrl" />
425
    
426
    <div class="live-dimensions">
427
      <p>Live Crop Dimensions:</p>
428
      <p>Width: {{ liveDimensions.width }}px</p>
429
      <p>Height: {{ liveDimensions.height }}px</p>
430
      <p>Aspect Ratio: {{ aspectRatio }}</p>
431
    </div>
432
  </div>
433
</template>
434

435
<script>
436
export default {
437
  data() {
438
    return {
439
      imageUrl: '/path/to/image.jpg',
440
      liveDimensions: { width: 0, height: 0 }
441
    };
442
  },
443
  computed: {
444
    aspectRatio() {
445
      const { width, height } = this.liveDimensions;
446
      if (height === 0) return 0;
447
      return (width / height).toFixed(2);
448
    }
449
  },
450
  mounted() {
451
    // Poll for dimension changes
452
    this.dimensionInterval = setInterval(() => {
453
      if (this.$refs.cropper) {
454
        this.liveDimensions = {
455
          width: this.$refs.cropper.cropW || 0,
456
          height: this.$refs.cropper.cropH || 0
457
        };
458
      }
459
    }, 100);
460
  },
461
  beforeUnmount() {
462
    if (this.dimensionInterval) {
463
      clearInterval(this.dimensionInterval);
464
    }
465
  }
466
};
467
</script>
468
```